OpenSimulator - User contributions [en]

Show stats

2014-07-23T14:32:34Z

Joe Radik: /* threadpool */

=Introduction=

"show stats" is a new statistics gathering mechanism is slowly being added to OpenSimulator to integrate previously separate and ad-hoc mechanisms. For this system, you can see a short statistics summary with the command "show stats" and a much longer list of statistics with the "show stats all" command (which unfortunately doesn't yet include those in the summary!).

Use the "help show stats" command on the console for more information.

See [[Monitoring]] for information on other statistics gathering mechanisms for OpenSimulator.

=General=
The full name of a stat has three components, separated by periods (.). In order, these are

* '''category''' - The category of the stat (e.g. server, scene)
* '''container''' - The containing object for this stat. For example, on scene this is the scene name (e.g. region 1). For server, this is the component to which the stat relates (e.g. memory, processor).
* '''name''' - The stat itself. For example, ClientLogoutsDueToNoReceives or SimFPS.

=Statistic types=

There are currently three types of statistic.

== Number ==
This is just a number, possibly with a unit. For example

server.threadpool.STPActiveThreads : 15 threads

== Change over time ==
This is a number that also shows the last delta between samples and also a moving average of deltas over the last 20 samples, each taken 5 seconds apart. For example

clientstack.test one.IncomingUDPReceivesCount : 98, 1.2/s, 1.7/s

== Percentage ==
This is a percentage with the antecedent and consequent also given. For example

clientstack.test one.PacketsReused : 37.91% (116/306)

=Statistics=

'''This information is highly subject to change as suitable data gathering is an evolving area. Need to keep adding stats.'''

==clientstack==

These are stats for the LLUDP clientstack that sends and receives UDP messages for viewers connected with the Second Life protocol. Each stats with clientstack.<region-name>.

{| border="1"
! Stat name !! Units !! Description
|-
| InboxPacketsCount || messages || The number of messages that have been pre-processed by an inbound network thread but are now waiting to be processed by the main Incoming Packets thread. If this number exceeds 0 for more than one sample then your simulator cannot cope with the number of UDP messages that clients are sending. Region performance will be degraded from the user perspective.
|-
| IncomingPacketPoolCount || messages || The number of packet objects currently in the memory pool to deal with incoming messages. This pool is used to reduce memory churn and hence improve simulator performance. The actual number is never an issue since OpenSimulator will create new pool objects as required.
|-
| IncomingPacketsMalformedCount || messages || Number of malformed packets that the simulator received from viewers. A high and increasing number may indicate a network attack.
|-
| IncomingPacketsOrphanedCount || messages || Number of well-formed packets that the simulator received but did not relate to any currently logged in viewer. Because viewers can disconnect in the middle of a datastream, we would expect to see a certain number of such packets in the course of normal operation. However, if the number is very high (e.g. tens of thousands) and/or increasing then this may indicate a network attack.
|}

==httpserver==

These are stats for OpenSimulator's built-in HTTP server. Statistics are partitioned (contained) by the incoming port number to which they relate. For example, httpserver.8002.HTTPRequestsServed are all the HTTP requests served that came in to port 8002.

{| border="1"
! Stat name !! Units !! Description
|-
| HTTPRequestsServed || requests || The number of HTTP requests served.
|-
| ProcessedPollResponses || responses || The number of responses sent to the viewer in response to poll requests.
|-
| QueuedPollResponses || responses || The number of responses queued for the next viewer poll.
|}

==scene==

These are stats relating to the graphical simulated scene.

Each starts with scene.<region-name>.

{| border="1"
! Stat name !! Units !! Description
|-
| RootAgents || avatars || The number of root agents in the scene. A root agent is associated with an avatar since a root agent is needed for full sim functionality (e.g. moving around).
|-
| ChildAgents || agents || The number of child agents in the scene. A child agent has limited functionality and is used by the viewer mainly to observe events in another scene (i.e. so that the user can see what's occuring in neighbouring regions).
|-
| FrameTime || ms || The amount of time taken by OpenSimulator to complete the last frame. The standard frame time is 18.18ms. In normal conditions there will be some small variation above and below this number, probably due to the low resolution of thread sleeping. This number may occasionally jump if the underlying VM (Mono or .NET) takes a long time to perform a garbage collect. If this number is consistently higher then your simulator is overloaded.
|-
| PhysicsTime || ms|| Amount of time spent performing physics engine operations in a scene frame. If this is consistently high enough to make the FrameTime exceed the 18.18ms standard then region performance will be degraded. You will need to reduce the number of physical objects in your region. For OpenSimulator 0.7.6, ODE is used single-threaded and so extra cores will make no difference to performance.
|-
| SpareTime || ms|| The amount of time that was left over after OpenSimulator had performed all operations required in the current scene loop. During this period OpenSimulator sleeps the thread.
|-
| SlowFrames || frames || In theory, this records the number of frames which took more than the standard frame time to execute. However, this measure may be buggy.
|}

==server==
These are stats relating to the server itself.

===thread===

These are the times in milliseconds since the monitored thread last performed any activity. This is the same as the "LAST UDPATE" information shown by the "show threads" command.

===threadpool===

These are server threadpool stats.

Each starts with server.threadpool.

{| border="1"
! Stat name !! Units !! Description
|-
| BuiltinThreadpoolIOCPThreadsAvailable || threads || The number of pooled thread objects waiting to handle incoming IO requests. OpenSimulator sets this to a very high number by default. If you ever see this approach zero then your simulator is severely overloaded with respect to processing raw incoming IO requests.
|-
| BuiltinThreadpoolWorkerThreadsAvailable || threads || The number of pooled thread objects in the Mono/.NET native threadpool available to handle requests. If you have async_call_method = UnsafeQueueUserWorkItem (or QueueUserWorkItem though "unsafe" is fine for our purposes) then is used for all OpenSimulator's threading requirements. If you have async_call_method = SmartThreadPool (which is the current default), then SmartThreadPool handles all the heavy thread launching requirements (and so see the server.threadpool.STP* stats). If this figure approaches zero then you simulator is severely overloaded.
|-
| STPInUseThreads || threads || The number of SmartThreadPool threads currently in use. If this climbs to the maximum allowed by STPMaxThreads then the simulator will experience general performance degradation. In this case, try increasing the MaxPoolThreads setting in the [Startup] section of OpenSim.ini (e.g. to 150).
|-
| STPMaxThreads || threads || Maximum number of threads that the SmartThreadPool will use. This is set by the MaxPoolThreads setting in the [Startup] section of OpenSim.ini (or OpenSimDefaults.ini).
|-
| STPWorkItemsWaiting || items || The number of work items waiting because all SmartThreadPool threads are busy with current work items. You will see this start to climb if STPInUseThreads == STPMaxThreads. You never want to see this situation - if you have work items waiting then try increasing your MaxPoolThreads setting.
|}

= stats record =
'''Please note that in OpenSimulator 0.7.6 this command was "debug stats record".'''

'''Unfortunately, a bug in OpenSimulator 0.8 means that the command "stats record start|stop" will not work properly and will report a usage error with the old command name. The workaround is to repeat the last command twice (e.g. "stats record start start").'''

This is an experimental facilty starting in OpenSimulator 0.7.6 which will record the results of "show stats all" to a log file every 5 seconds. The aim is to record statistical information throughout a session for later analysis. The logging is enabled with the console command. It works on both the simulator and a ROBUST instance.

# stats record start
Now recording all stats to file every 5000ms

To stop logging, either shutdown the server or use the command

# stats record stop
Stopped recording stats to file.

The log file used has the same name as the main logfile for the executable with the word "Stats" appended. For instance, turning on stats logging for OpenSim.exe will write to the file OpenSimStats.log. For Robust.exe, this will write to RobustStats.log.

Currently and in OpenSimulator 0.7.6, this logging requires entries in OpenSim.exe.config (and Robust.exe.config for Robust). If you are using your own version of these files then you will need to adapt them for the logging entries.

The performance impact of such logging should be low, though the log file size can grow quite large.

== Analysis ==
Tools to analyze record stats data are under development at https://github.com/justincc/opensimulator-tools/tree/master/analysis/opensimulator-stats-analyzer. This includes summary and graphing tools.

= stats save =
'''Command added in development code from 20th March 2014.'''

This command will save a snapshot of current statistical data to a given path. For example

# stats save stats.txt

If the file already exists, the stats will be appended.

Show stats

2014-07-23T14:10:34Z

Joe Radik: /* Analysis */

=Introduction=

"show stats" is a new statistics gathering mechanism is slowly being added to OpenSimulator to integrate previously separate and ad-hoc mechanisms. For this system, you can see a short statistics summary with the command "show stats" and a much longer list of statistics with the "show stats all" command (which unfortunately doesn't yet include those in the summary!).

Use the "help show stats" command on the console for more information.

See [[Monitoring]] for information on other statistics gathering mechanisms for OpenSimulator.

=General=
The full name of a stat has three components, separated by periods (.). In order, these are

* '''category''' - The category of the stat (e.g. server, scene)
* '''container''' - The containing object for this stat. For example, on scene this is the scene name (e.g. region 1). For server, this is the component to which the stat relates (e.g. memory, processor).
* '''name''' - The stat itself. For example, ClientLogoutsDueToNoReceives or SimFPS.

=Statistic types=

There are currently three types of statistic.

== Number ==
This is just a number, possibly with a unit. For example

server.threadpool.STPActiveThreads : 15 threads

== Change over time ==
This is a number that also shows the last delta between samples and also a moving average of deltas over the last 20 samples, each taken 5 seconds apart. For example

clientstack.test one.IncomingUDPReceivesCount : 98, 1.2/s, 1.7/s

== Percentage ==
This is a percentage with the antecedent and consequent also given. For example

clientstack.test one.PacketsReused : 37.91% (116/306)

=Statistics=

'''This information is highly subject to change as suitable data gathering is an evolving area. Need to keep adding stats.'''

==clientstack==

These are stats for the LLUDP clientstack that sends and receives UDP messages for viewers connected with the Second Life protocol. Each stats with clientstack.<region-name>.

{| border="1"
! Stat name !! Units !! Description
|-
| InboxPacketsCount || messages || The number of messages that have been pre-processed by an inbound network thread but are now waiting to be processed by the main Incoming Packets thread. If this number exceeds 0 for more than one sample then your simulator cannot cope with the number of UDP messages that clients are sending. Region performance will be degraded from the user perspective.
|-
| IncomingPacketPoolCount || messages || The number of packet objects currently in the memory pool to deal with incoming messages. This pool is used to reduce memory churn and hence improve simulator performance. The actual number is never an issue since OpenSimulator will create new pool objects as required.
|-
| IncomingPacketsMalformedCount || messages || Number of malformed packets that the simulator received from viewers. A high and increasing number may indicate a network attack.
|-
| IncomingPacketsOrphanedCount || messages || Number of well-formed packets that the simulator received but did not relate to any currently logged in viewer. Because viewers can disconnect in the middle of a datastream, we would expect to see a certain number of such packets in the course of normal operation. However, if the number is very high (e.g. tens of thousands) and/or increasing then this may indicate a network attack.
|}

==httpserver==

These are stats for OpenSimulator's built-in HTTP server. Statistics are partitioned (contained) by the incoming port number to which they relate. For example, httpserver.8002.HTTPRequestsServed are all the HTTP requests served that came in to port 8002.

{| border="1"
! Stat name !! Units !! Description
|-
| HTTPRequestsServed || requests || The number of HTTP requests served.
|-
| ProcessedPollResponses || responses || The number of responses sent to the viewer in response to poll requests.
|-
| QueuedPollResponses || responses || The number of responses queued for the next viewer poll.
|}

==scene==

These are stats relating to the graphical simulated scene.

Each starts with scene.<region-name>.

{| border="1"
! Stat name !! Units !! Description
|-
| RootAgents || avatars || The number of root agents in the scene. A root agent is associated with an avatar since a root agent is needed for full sim functionality (e.g. moving around).
|-
| ChildAgents || agents || The number of child agents in the scene. A child agent has limited functionality and is used by the viewer mainly to observe events in another scene (i.e. so that the user can see what's occuring in neighbouring regions).
|-
| FrameTime || ms || The amount of time taken by OpenSimulator to complete the last frame. The standard frame time is 18.18ms. In normal conditions there will be some small variation above and below this number, probably due to the low resolution of thread sleeping. This number may occasionally jump if the underlying VM (Mono or .NET) takes a long time to perform a garbage collect. If this number is consistently higher then your simulator is overloaded.
|-
| PhysicsTime || ms|| Amount of time spent performing physics engine operations in a scene frame. If this is consistently high enough to make the FrameTime exceed the 18.18ms standard then region performance will be degraded. You will need to reduce the number of physical objects in your region. For OpenSimulator 0.7.6, ODE is used single-threaded and so extra cores will make no difference to performance.
|-
| SpareTime || ms|| The amount of time that was left over after OpenSimulator had performed all operations required in the current scene loop. During this period OpenSimulator sleeps the thread.
|-
| SlowFrames || frames || In theory, this records the number of frames which took more than the standard frame time to execute. However, this measure may be buggy.
|}

==server==
These are stats relating to the server itself.

===thread===

These are the times in milliseconds since the monitored thread last performed any activity. This is the same as the "LAST UDPATE" information shown by the "show threads" command.

===threadpool===

These are server threadpool stats.

Each starts with server.threadpool.

{| border="1"
! Stat name !! Units !! Description
|-
| BuiltinThreadpoolIOCPThreadsAvailable || threads || The number of pooled thread objects waiting to handle incoming IO requests. OpenSimulator sets this to a very high number by default. If you ever see this approach zero then your simulator is severely overloaded with respect to processing raw incoming IO requests.
|-
| BuiltinThreadpoolWorkerThreadsAvailable || threads || The number of pooled thread objects in the Mono/.NET native threadpool available to handle requests. If you have async_call_method = UnsafeQueueUserWorkItem (or QueueUserWorkItem though "unsafe" is fine for our purposes) then is used for all OpenSimulator's threading requirements. If you have async_call_method = SmartThreadPool (which is the current default), then SmartThreadPool handles all the heavy thread launching requirements (and so see the server.threadpool.STP* stats). If this figure approaches zero then you simulator is severely overloaded.
|-
| STPInUseThreads || threads || The number of SmartThreadPool threads currently in use. If this climbs to the maximum allowed by STPMaxThreads then the simulator will experience general performance degradation. In this case, try greating increasing the MaxPoolThreads setting in the [Startup] section of OpenSim.ini (e.g. to 150).
|-
| STPMaxThreads || threads || Maximum number of threads that the SmartThreadPool will use. This is set by the MaxPoolThreads setting in the [Startup] section of OpenSim.ini (or OpenSimDefaults.ini).
|-
| STPWorkItemsWaiting || items || The number of work items waiting because all SmartThreadPool threads are busy with current work items. You will see this start to climb if STPInUseThreads == STPMaxThreads. You never want to see this situation - if you have work items waiting then try increasing your MaxPoolThreads setting.
|}

= stats record =
'''Please note that in OpenSimulator 0.7.6 this command was "debug stats record".'''

'''Unfortunately, a bug in OpenSimulator 0.8 means that the command "stats record start|stop" will not work properly and will report a usage error with the old command name. The workaround is to repeat the last command twice (e.g. "stats record start start").'''

This is an experimental facilty starting in OpenSimulator 0.7.6 which will record the results of "show stats all" to a log file every 5 seconds. The aim is to record statistical information throughout a session for later analysis. The logging is enabled with the console command. It works on both the simulator and a ROBUST instance.

# stats record start
Now recording all stats to file every 5000ms

To stop logging, either shutdown the server or use the command

# stats record stop
Stopped recording stats to file.

The log file used has the same name as the main logfile for the executable with the word "Stats" appended. For instance, turning on stats logging for OpenSim.exe will write to the file OpenSimStats.log. For Robust.exe, this will write to RobustStats.log.

Currently and in OpenSimulator 0.7.6, this logging requires entries in OpenSim.exe.config (and Robust.exe.config for Robust). If you are using your own version of these files then you will need to adapt them for the logging entries.

The performance impact of such logging should be low, though the log file size can grow quite large.

== Analysis ==
Tools to analyze record stats data are under development at https://github.com/justincc/opensimulator-tools/tree/master/analysis/opensimulator-stats-analyzer. This includes summary and graphing tools.

= stats save =
'''Command added in development code from 20th March 2014.'''

This command will save a snapshot of current statistical data to a given path. For example

# stats save stats.txt

If the file already exists, the stats will be appended.

Configuration

2014-06-27T15:48:45Z

Joe Radik: /* Running multiple ROBUST service instances */

{{Quicklinks}}
 
== OpenSimulator simulator configuration file ==
The region simulator configuration is managed using a file called OpenSim.ini. This file is used regardless of whether the sim is running in standalone or grid mode. This file references some additional configuration information from the config-include/ directory. Information about the various settings is contained in the OpenSim.ini file itself (or OpenSim.ini.example for reference).

Please note, that the name OpenSim.ini can be changed via [[OpenSim.exe Command Line Options|command line arguments]].

It is also possible to distribute the inifile settings over two files. This is useful if you want to run several OpenSimulator processes where most of your settings are identical except for a few. The master file is read first, then the inifile is read. Settings given in the inifile overrule settings given in the master file. The master file has the same format and the same keywords as the inifile, so the same documentation applies.

== Database ==

Opensim supports the following database-engines. Information about setting these up can be found in the OpenSim.ini.example file and the other various example files in bin/config-include. '''If you do not want to use the default SQLite configuration then you will need to setup your database before proceeding further'''. SQLite does not require further configuration. See [[Database Settings]] for the detailed settings.

* '''SQLite''' (default) - a lightweight database that comes bundled with OpenSimulator and can be used without requiring any extra configuration. It is mostly intended to get you up and running quickly, not for production use. It is significantly slower than MySQL. A few features here (such as attachment persistence) have not yet been fully implemented.

* '''MySQL''' (fully supported) - This is the recommended database for any use beyond experimentation or small standalone applications. The minimum MySQL version is 5.1.
::* '''Windows x64 systems:'''  There is currently an unresolved [http://opensimulator.org/mantis/bug_view_advanced_page.php?bug_id=5294 bug_id=5294] found when running OpenSimulator with MySQL 5.5 on Windows x64 systems.
::* '''Opensim 0.7.0.2:'''  Some users have reported problems with MySQL 5.1.55 and up with Opensim 0.7.0.2, see [http://opensim-users.2152040.n2.nabble.com/OpenSim-1-7-0-2-and-MySQL-Versions-td6155064.html this thread] for more information. The issue can be resolved by using an updated version of MySql.Data.dll OR installing an older version of MySQL such as [http://downloads.mysql.com/archives.php?p=mysql-5.1&v=5.1.52 MySQL 5.1.52] with Opensim version 0.7.0.2.  

* '''MSSQL''' (fairly supported) - persistence support for some recent OpenSimulator features may not yet be implemented though the vast majority of them are supported.

== Standalone vs. Grid ==
We recommend that you first get OpenSimulator running in standalone mode before you attempt to connect it to a grid or run your own grid. OpenSimulator will start up in standalone mode out-of-the-box on the binary distributions.

An OpenSimulator configuration consists of regions (run by region simulators) and backend data services (such as user, assets and inventory management).

A system running in '''standalone mode''' runs both the region simulator and all the data services in a single process when you run OpenSim.exe. In this mode you can run as many regions as you like but only on a single machine.

[[Image:Opensim-standalone.png|frame|center|OpenSimulator running in standalone mode. Both simulator and services run in the same process (OpenSim.exe).]]

In '''grid mode''', the data services are not part of the region server process. Instead, they are run in a separate executable called Robust.exe. A Robust shell can run all the services or they can be split amongst any number of Robust instances. This allows them to be run on entirely separate machines if necessary. In this mode, the OpenSim.exe acts solely as the region server, serving one or more regions that communicate with the separate data services. At this point you can run multiple OpenSim.exe region simulators on different machines.

[[Image:Opensim-grid-simple.png|frame|center|OpenSimulator running in grid mode. In this case, all the services are being run within a Robust.exe process. Multiple copies of OpenSim.exe (usually running on different machines) all use the same set of common services.]]

Running in grid mode is more complicated than running in standalone mode. It requires an understanding of UUID, X,Y location, server handshake passwords, estates and estate owners, and a couple of other settings. These require more care and patience to set up. We strongly recommend that you don't attempt this unless you are extremely patient and very technically proficient.

= Running OpenSimulator in Standalone mode =

Binary distributions of OpenSimulator are by default configured to run in standalone mode.

However, if you build OpenSimulator from the source distribution or from the git repository then you will need to:

# Change into the '''''bin''''' folder
# Copy the file '''''OpenSim.ini.example''''' to '''''OpenSim.ini'''''. This configures the 3D simulator itself.
# Change into the '''''bin/config-include''''' folder
# Copy the file '''''StandaloneCommon.ini.example''''' to '''''StandaloneCommon.ini'''''. This configures the in-process data services used by the standalone configuration.
# In the '''[Architecture]''' section of '''''OpenSim.ini''''', near the bottom of the file, uncomment the ''Standalone.ini'' line. To uncomment a line of code, remove the semi-colon (;) comment symbol preceding the line so that it says:

Include-Architecture = "config-include/Standalone.ini"

Running OpenSimulator is then a matter of launching OpenSim.exe. However, you need to have installed all dependencies before that. See [[Dependencies]] for details. After that, open a command prompt (for Windows users, Start menu > Run > cmd) and navigate to the Opensim /bin directory.

On a '''Windows 32-bit''' command prompt:
OpenSim.exe
Under '''Windows 64-bit''', ODE cannot yet be compiled for 64 bit mode, so if using the default ODE physics plugin run:
OpenSim.32BitLaunch.exe
On '''Linux''' run:
mono OpenSim.exe
This can be done under both 32 and 64 bit modes with the ODE physics engine.

== Running for the first time ==

If you're running OpenSimulator for the first time, it will ask you several questions at the console that will set up a single region for you. The configuration options you enter will be written to the bin/Regions/Regions.ini file, which you can then edit at a later date if you need to make changes.

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. The only time when you wouldn't is if you were trying to set up a configuration to point to pre-existing region data. But in this case you are probably better off editing the Regions.ini file directly anyway
* '''Region Location'''
::This is the location of the region on the grid. In standalone mode you can safely leave these as the default (1000,1000). If you were to set up additional regions later on in Regions.ini then they would need different grid co-ordinates (e.g. 1000,1001). OpenSimulator regions can be placed anywhere on a 65536 by 65536 grid, but [[Hypergrid]] enabled regions may need special consideration for region location. See [[Installing and Running Hypergrid#The 4096 Regions Limit]] for more information.
* '''Internal IP address'''
::In virtually all cases this can be left as 0.0.0.0 (this is a wildcard that allows OpenSimulator to listen for UDP connections on any of the server's network interfaces). If you want to restrict UDP connections to only one network interface then you can specify an explicit IP address. This address is only used internally - the '''External host name''' is the one that is actually passed to the viewer (and hence is the important one).
* '''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'''
::If you leave this at the default 'SYSTEMIP' then this will become the LAN network address of the machine (e.g. 192.168.1.2). This is fine if you are connecting only from within your LAN. If you want to connect to it from a client on the internet, this should be the External IP Address of your router. Fully Qualified Domain Names (FQDNs) can also be used though they will be converted to a numeric IP address before being sent to the viewer.

The following details are also asked in OpenSimulator 0.6.9 and earlier.

* '''Master Avatar UUID'''
::This is a legacy OpenSimulator feature and can be left at the default of 00000000-0000-0000-0000-000000000000. Later on, you may want to change this to your own avatar's UUID in Regions.ini if you have problems editing terrain.
* '''Master Avatar first name'''
::This is an alternative way of specifying the master avatar by avatar name rather than UUID. If you press enter here then both this field and the last name field will be left blank. Accepting the blank default is fine - this can always be changed later in Regions.ini file.
* '''Master Avatar last name'''
::The last name of the master avatar.
* '''Master Avatar sandbox password'''
::The password of the master avatar.

In OpenSimulator 0.7 and later, OpenSimulator will ask you to assign each region to an estate during the setup process. If an estate needs to be created then it will also ask you to assign an estate manager. In standalone mode, an estate manager can also be created during the setup process.

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. This is also a user account that you can use to perform your initial login test.

See [[Configuring Regions]] for more information about the Regions.ini file that these questions generate.

If you want to create a user other than the estate manager, then in the server console type:

create user

This will ask you a series of questions for creating a user (such as first name, last name and password).

== Network access for the standalone installation ==
In standalone mode, a viewer connecting to your installation needs the following network access to your installation machine.

1. TCP over the http_listener_port as used in your simulator. This is set in the [Network] section of your OpenSim.ini.

<source lang="ini">
[Network]
http_listener_port = 9000
</source>

This will be the default of 9000 if you have not explicitly changed it.

2. UDP over each region's InternalPort as configured in your region files (such as Regions.ini). For instance, if you have configured

<source lang="ini">
[test]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c81
Location = 1000,1000
InternalAddress = 0.0.0.0
InternalPort = 9000
AllowAlternatePorts = False
ExternalHostName = mygrid.com

[test2]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c82
Location = 1000,1001
InternalAddress = 0.0.0.0
InternalPort = 9001
AllowAlternatePorts = False
ExternalHostName = mygrid.com
</source>

then you will need to open ports 9000 and 9001 to UDP traffic.

3. The network address of the machine hosting the OpenSimulator installation must be accessible to connecting viewers. In the example above, the installation machine is reachable from the Internet via the domain name "mygrid.com". If the same installation needs to be accessed by viewers on the same network, it must be possible for them to also successfully resolve that domain name (not all routers, especially home routers, have this "loopback capability").

If the installation only needed to be accessed on the same LAN, then one could you the local IP address of the server (e.g. 192.168.1.2).

== Connecting to a standalone installation ==

To connect to your new sim with your user, start up a Second Life viewer with the following command line switches:

'''Client on same machine as OpenSim:'''
-loginuri http://127.0.0.1:9000

'''Client on same LAN as OpenSim:'''
-loginuri http://lan_ip:9000

'''Client on different machine or internet:'''
-loginuri http://external_ip:9000

Then enter the user name and password you set up in the previous step and your new user should login.

Be aware of [http://osgrid.org/forums/viewtopic.php?f=5&t=400&start=0&st=0&sk=t&sd=a loopback] problems when Running viewer & server(s) on the same machine (LAN) by using the "external" configuration. ('''You might notice endless waiting for region handshake'''.) See also [[Troubleshooting|troubleshoot hints]]. If you're having Connectivity problems, [[Network Settings|be sure to read the Network Configuration Page]]. This is important if you see Region handshake issue.

[[Image:Exclamation.png|left]]
== IMPORTANT NOTE, DIVA DISTRO - 4 Apr. 2012 - ==

'''If you download the latest version of diva-r18611.tar.bz''', it is necessary to first launch the setup program ''configure.exe''
*In Linux or MacOSX : open a terminal and enter "mono /diva-r18611/bin/Configure.exe" (assuming that you have placed the Diva distro in /diva-r18611)
*In Windows, assuming they extracted Diva in My Documents, one would open "Run => cmd" and enter '''cd "%USERPROFILE%\My Documents\diva-r18611\"'', followed by "Configure.exe".
After issuing the command, you can set your sim's domain name, and carefully answer the program's questions, then start the program as instructed in above paragraphs.

The program will install the optimum configuration for OpenSim, example: '''<nowiki>http://<your_IP>:9000</nowiki>''' and WiFi '''<nowiki>http:<your_IP>:9000/wifi</nowiki>'''
In the standalone version, four regions will be set up. You can optionally add other regions later on, so make sure to use the same first name with the addition of a number
(ex: "region 5", "region 6", "region 7", etc. otherwise you can't enter the region and you'd be placed in the nearest free location.

If you wish to enter a different region name, make sure that the "distance" between the island created by the Wifi configuration program and the next,
will be at least 40 positions away from the first installed region)
(command console: create region Johnnyland RegionConfigure.ini)

= Running OpenSimulator in Grid mode =
{|
| style="background:LavenderBlush; color:black" |
[[Image:Exclamation.png|left]]
NOTE: 0.7 is the first OpenSimulator release that fully migrates all services to the ROBUST server shell. OpenSim.Grid.UserServer.exe and MessageServer.exe from OpenSimulator 0.6.9 are no longer necessary. Please see the [[0.7 Release|0.7 release notes]] for more details. For details on how to set up grid services in OpenSimulator 0.6.9 and earlier please see [[OpenSim 0.6.9 Grid Mode Configuration]]
|}

Running OpenSimulator in grid mode is considerably more complicated than running a standalone instance. Instead of running everything in the same process, backend data services (asset, inventory, etc.) run in one or more separate processes, often on a different machine. This allows multiple OpenSim.exe simulator instances to use the same asset and inventory data.

== Step 1: Set up a ROBUST services instance ==

1. In the bin directory, copy Robust.ini.example to Robust.ini. The example file is configured to run all the services in a single ROBUST instance.

2. Configure the [[Database Settings]] in Robust.ini to use your MySQL database. Only MySQL is supported for running grid services.

3. Start up Robust.exe.

mono Robust.exe (Linux, BSD, Mac OS X)

or

Robust.exe (Windows)

If you don't see any errors (in red) on the console then you can move on to the next step.

4. Every region must belong to an estate, and every estate must have an owner which is a valid user account in OpenSim's user account service. Create a user on the ROBUST command console with the following command.

create user

This will ask you for the user's name, password and an optional e-mail. Remember this name since you will need it when you start up the simulator for the first time.

== Step 2: Configure an OpenSim.exe to use the ROBUST services ==

In grid mode, as in standalone mode, you need to configure OpenSim.ini which controls the 3D simulator itself.

However, instead of using and configuring the file config-include/StandaloneCommon.ini, a simulator connecting to a grid needs to use and configure the config-include/GridCommon.ini file, in order to connect to the ROBUST hosted remote data services rather than in-process local ones.

The steps for both these operations are as follows.

1. Copy bin/OpenSim.ini.example to OpenSim.ini

2. Find the [Architecture] section at the very bottom of OpenSim.ini. Make sure that one of the following lines is uncommented:

Include-Architecture = "config-include/Grid.ini" (in OpenSimulator 0.7.1 and later)

or

Include-Grid = "config-include/Grid.ini" (in OpenSimulator 0.7.0.2 and earlier)

The others should remain commented.

3. Go to bin/config-include and copy GridCommon.ini.example to GridCommon.ini.

4. Open GridCommon.ini in a text editor. You will see lots of URL entries, each of which have dummy defaults of http://myassetserver.com:8003, http://myinventoryserver.com:8003, etc. You will need to change each of these to point towards the address of your ROBUST instance. For instance, if you're running ROBUST on a machine with a local IP address of 192.168.1.2, you will need to change AssetServerURI to the setting

AssetServerURI = "http://192.168.1.2:8003"

5. Run OpenSim.exe. If you're running OpenSim.exe for the first time you will get the same questions about setting up the region that occur on a first-run in standalone mode. Please see the standalone section for instructions on how to answer these, or read more information about the Regions.ini file on the [[Configuring Regions]] page.

If everything is set up correctly, when starting up OpenSim.exe you shouldn't see any errors. You should also see the ROBUST console display log lines saying that the region has registered with the grid service. For example,

21:43:45 - [GRID SERVICE]: Region t1 (176cc95e-f693-4b02-8e08-af86e2372faa) registered successfully at 256000-256000
21:43:47 - [GRID SERVICE]: region t1 has 0 neighbours

== Network access for a grid installation ==
In standalone mode, a viewer connecting to your installation needs to access

# The login service over TCP and other configured public services (e.g. grid info, map).
# The http_server_port of each configured simulator over TCP.
# The InternalPort and ExternalHostName of each configured region.

The last two requirements are the same as for standalone installations, except that they apply to each server that hosts a simulator. Please see the standalone section above for more details.

The login service is a little different. Whereas in standalone this uses the same http_server_port as the simulator itself, in grid mode it's running in a separate ROBUST service.

The default port for the login service is 8002. You can see this used in the [ServiceList] section of Robust.ini.example.

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8003/OpenSim.Server.Handlers.dll:AssetServiceConnector"
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

Here all the public services (those where the viewer connects directly to the service) are served on port 8002, with internal services on 8003. So you need to make sure that the viewer can access port 8002 over TCP but you do not want to expose port 8003. Only simulators need to be able to connect to port 8003.

== Connecting to a grid installation ==

Your client startup line will look something like

-loginuri http://mygrid.com:8002

The loginuri needs to be the address to the login service. In standalone mode, this was the same address as the region simulator and the port was 9000 by default. However, in grid mode it will be the address to login service hosted on the ROBUST instance. In this case, the address will be 192.168.1.2. The port number of 8002 is the traditional one for the grid login service and is the default in Robust.ini.example.

If the login is successful, you will see log lines on the ROBUST console (for the login itself) and then log lines on the region simulator console (as the login process tells the simulator to expect the avatar, tells the viewer the address of the region simulator and then when the viewer starts talking to the simulator directly).

= Running multiple ROBUST service instances =

If you are operating a grid, then you can run different services (e.g. asset, inventory) in different ROBUST instances, in order to spread the load. To do this, you will need to edit the ServiceConnectors parameter in the [Startup] section of Robust.ini (or Robust.HG.ini if you're running Hypergrid). The default ServiceConnectors parameter looks something like this

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8003/OpenSim.Server.Handlers.dll:AssetServiceConnector"
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

Each entry has the form

<port-number>/<dll>:<connector-class-name>

For instance, the first entry above

8003/OpenSim.Server.Handlers.dll:AssetServiceConnector

says to start an AssetServiceConnector (and hence an asset service) from the OpenSim.Server.Handlers.dll and to server that from port 8003.

By default, Robust.exe loads a configuration file with the same name but with .ini appended instead of .exe. So Robust.exe will look for an inifile called Robust.ini. You can change this by giving the parameter on the commandline. For instance, to start Robust with HG parameters, one would use

Robust.exe -inifile=Robust.HG.ini

So if you wanted to run every connector apart from assets in one instance of ROBUST and the asset connector in another instance, you would have two ini files. One could remain Robust.ini and have

<source lang="ini">
[ServiceList]
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

The other could be called Robust.Assets.ini and have

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8004/OpenSim.Server.Handlers.dll:AssetServiceConnector"
</source>

Note that this is using port 8004 instead of port 8003. This is necessary since only one executable can use each port at a time. You will need to make sure your simulator configuration files use port 8004 for the asset service as well.

You will also need to change the default network port to 8004 for this second copy of Robust.exe

<pre>
[Network]
port = 8004
</pre>

Once you've created the two ROBUST configuration files (Robust.ini containing all services apart from asset and Robust.Assets.ini containing only the asset service), then you could start the first Robust.exe as usual.

Robust.exe

This will load Robust.ini, as we haven't specified a Robust.ini. Also, the logfile it will use will be Robust.log as we haven't manually specified one.

The second ROBUST instance we would start with

Robust.exe -inifile=Robust.Assets.ini -logfile=Robust.Assets.log

The -inifile switch tells the second Robust instance to load it's configuration from Robust.Assets.ini rather than Robust.ini. The -logfile switch tells Robust.exe to use Robust.Assets.log as its logfile rather than the default Robust.log. If you don't specify this switch then you may see errors on the console about a locked log file.

At this point you should have two running Robust.exe instances.

If you put the ROBUST instances on different machines then don't forget to change the relevant service URIs in each simulator to match.

Since OpenSimulator services are stateless (e.g. every request is unconnected with other requests as long as they affect the same persistent data where necessary), you can also load balance by starting more than one ROBUST instance with a copy of the same service (e.g. multiple asset services using the same database). Requests would be round-robined between the service copies using an HTTP reverse proxy implementation (e.g. nginx). See [[Performance#Services]] for more details.

== Notes ==
[http://opensimulator.org/pipermail/opensim-users/2012-October/011099.html Useful discussion about separating Robust instances]

= Attaching your sim to someone else's grid =

To set up the region server (i.e., <tt>OpenSim.exe</tt>) to connect to an external grid, follow the [[Configuration#Step 2: Configure an OpenSim.exe to use the ROBUST services]] instructions above.

The grid will have already provided with the required services. In step 2 you will need to use the provided URLs for their services.

In your bin/Regions.ini file (or other region config file) you will also need to set the grid co-ordinates to your regions provided from the grid operator. See [[Configuring Regions]] for more information.

= Running an OpenSimulator standalone or grid installation with Hypergrid enabled =
[[Hypergrid]] is an emerging architecture supported by OpenSimulator that allows a user with an account on one standalone or grid to visit other Hypergrid-enabled standalones or grids, and for users from those grids to visit the home grid. This does not require the two installations to share a central set of data services (assets, inventory, etc.). Please see [[Installing and Running Hypergrid]] for more details.

= Further notes =

== Troubleshooting ==

See [[Troubleshooting]]

== Running OpenSimulator 0.6.7 to 0.7.6.1 in 64 bit Windows ==
[[Image:Exclamation.png|left]]
As of OpenSimulator 0.6.7 and up to release 0.7.6.1, the default physics engine for OpenSimulator was changed to the ODE engine. This is because ODE was the most advanced physics engine plugin at the time in OpenSimulator. Unfortunately, it has the drawback in that its library is not compilable under 64-bit in Windows.

Therefore, in order to launch the region simulator under 64-bit Windows for versions 0.6.7 to 0.7.6.1 using ODE, users may need to run:

OpenSim.32BitLaunch.exe

instead of:

OpenSim.exe

An alternative is to use the basicphysics engine instead or one of the other alternative physics engines bundled with OpenSim, though all these were less functional than the ODE plugin.

From OpenSim 0.8 the default physics engine is BulletSim.

== Note About Mono ==

Mono and .NET have a built in threadpool. By default, OpenSimulator is instead configured to use a third-party threadpool called SmartThreadPool for many tasks, partly because of issues with early implementations of the Mono threadpool.

However, even with this setting, some other operations are carried out with the built-in threadpool. At least in some versions of Mono (chiefly prior to 2.6), the default configuration for this can cause issues with OpenSimulator - [http://www.mono-project.com/ThreadPool_DeadLocks ThreadPool_Deadlocks at the mono-project website].

If this is an issue or if the threadpool runs out of available threads, then the operation of your sim will start to break in all sorts of different ways. A common symptom is the freezing of all activity upon login of a new avatar.

The MONO_THREADS_PER_CPU parameter affects the number of existing built-in threadpool worker threads below which Mono will always spawn a new thread when OpenSimulator adds a new task. This is MONO_THREADS_PER_CPU * 4. So if set to 50, the minimum number of worker threads will be 200.

Above this number, Mono will make an internal decision whether to spawn a new thread or wait for an existing thread to complete its task.

The effect of this parameter is extremely implementation dependent, and so dependent upon the version of Mono that you are using. Before 2.6 for instance, it was definitely worth setting a high MONO_THREADS_PER_CPU due to issues with the Mono thread pool. In theory, later versions of Mono should not be susceptible to this issue. Mono 2.10.8.1, for instance, has a default MONO_THREADS_PER_CPU of 1 (despite what the incorrect Mono manpage says).

However, people still report a benefit from setting MONO_THREADS_PER_CPU higher than default. The exact number depends on many factors including: the number of CPUs in your machine, what else you use that machine for, how many regions you have in your sim, how many of them are adjacent, how many scripts you have, and how many avatars you expect to serve at the same time. As a reference, Wright Plaza in OSGrid, which is running as a single region on a sim and routinely hosts meetings with 20 avatars, uses the value 125.

For example: $ export MONO_THREADS_PER_CPU=125

So if you are having problems with avatars freezing and you're hardware meets or exceeds recommended [[Performance]] requirements, then you may want to setting this environment variable.

There is a very basic program for displaying current threadpool configuration settings at https://github.com/justincc/opensimulator-tools/tree/master/analysis/threadpool-info.

All this applies to the min threadpool numbers, not the max thread numbers. OpenSimulator itself will attempt to adjust the max numbers. You can see the output from this very near the top of the OpenSim.log file.

== Increasing the stack reserve level when using OpenDynamicsEngine on *nix ==

If you have problems using the OpenDynamicsEngine on *nix, try setting your stack reserve level higher than the default with the following command;
<tt>ulimit -s 262144</tt> Or, run the opensim-ode.sh to start up OpenSimulator.

== Firewalls ==
Some operation systems or distributions run their own firewall by default. If you can't access to OpenSimulator from remote client, you'll need to check their settings. See [[Firewall Settings]] for details.

== Legacy Configuration Information ==
These are some pages containing some legacy configuration information of unknown accuracy.

[[OpenSim 0.6.6 legacy configuration information]]

== Additional Optional Configuration Tasks ==

=== Further configure OpenSimulator ===
If you've looked through OpenSim.ini.example or any other of the config files, you'll see that there's a very large number of configurable parameters spread across multiple files. See [[Configuring Simulator Parameters]] for more details about the configuration infrastructure and how settings in identically named sections (e.g. [XEngine]) are merged by OpenSimulator on loading.

=== Set up a second region to run on the same simulator ===
See [[Configuring Regions]].

=== Run Multiple Standalone Instances of OpenSimulator on the Same Server ===
For each subsequent instance of OpenSim, change the 'http_listener_port' in OpenSim.ini to the value excluding 9000, and 'InternalPort' in Regions.ini to the value excluding 9000. Also, make sure your regions are using different ports, as explained in [[Configuring Regions]].

=== Load region content ===
You can load content onto regions by using the [[OpenSim Archives|load oar command]]. To load individual OAR files into each region, use the 'change region [regionname]' command and then 'load oar [oar-location]'.

=== OpenSim.exe command line options ===
OpenSim.exe has command line options which allow you to perform actions such as reading configuration files from a different directory. See [[OpenSim.exe Command Line Options]] for more details.

=== Script engine ===
OpenSimulator supports multiple script engines. See [[ScriptEngines]] for details. If you don't know what this means then the default script engine will be fine. In fact, recent versions of OpenSimulator only ship with one script engine, the XEngine.

=== Permissions Configuration ===
OpenSimulator has a quite elaborate set of permissions. See [[Permissions (Server)]] for details. By default, permissions are active on region simulators.

=== Logging ===
By default, OpenSimulator logs information to a file called OpenSim.log in the bin directory. See [[Logging]] for details on how to further configure this if required.

=== Set up other optional modules ===
* [[IRCBridgeModule]]
* [[Freeswitch Module]]
* [[Offline Messaging]]
* [[Enabling Groups]]
* See also [[User_Documentation#Setup]]

=== Configuration of Web Server and Pages ===
OpenSimulator contains a web server that can serve up a variety of pages. Some which come from external files and some are generated internally.
* [[External Files]]
* [[Internally Generated]]

= Where to go from here =

* [[NAT Loopback Routers]] Router and Nat Loopback Information

* [[Upgrading]] from an old OpenSimulator version to a newer one.

* [[Server Commands]] for creating users and controlling the system.

* Fix the bent knees bug: [[FAQ#Why are my knees bent when I stand idle.3F]]

= References =

* [http://dist.opensimulator.org/wiki/opensim-standalone.odg OpenOffice draw file for OpenSimulator standalone diagram]
* [http://dist.opensimulator.org/wiki/opensim-grid-simple.odg OpenOffice draw file for OpenSimulator grid diagram]

[[Category:Configuration]]

0.7 Release

2013-11-07T13:53:28Z

Joe Radik: /* Hypergrid changes */

= Release Notes =

== Major changes from 0.6.x ==

Release 0.7 features the completed major refactoring and rearchitecting work that happened during the second half of 2009 and the first quarter of 2010. This work targeted mainly the resource services and servers previously known as UGAIM. These servers have been replaced by one single server shell called [[ROBUST]] which can now run any combination of services in it.

The standard opensim release includes configuration files for two deployment architectures:

* The standalone deployment consists in having both the simulator and the services in one single process, OpenSim.exe, configured by OpenSim.ini (and included .inis under bin/config-include).
* The grid deployment has 1 ROBUST server process (Robust.exe) running all services, configured by Robust.ini (or Robust.HG.ini); and one or more simulators (OpenSim.exe), each configured by OpenSim.ini (and included .ini files under bin/config-include).

Users and distributors of OpenSimulator can deviate from these pre-existing configurations in many ways. Specifically, large grids will benefit from splitting the single ROBUST server into several ROBUST servers, each running a collection of services. Instructions for how to do that are found elsewhere. (Think of the ROBUST server as an Apache server, to which you can load service modules)

The services themselves have been reconceptualized; we now have the following set of main services:

* Assets -- the asset store
* Authentication -- passwords and auth tokens
* Authorization -- access control
* Avatar -- the visual representation of users, formerly known as "avatar appearance"
* FreeSwitch -- voice
* Friends -- social net
* Gatekeeper -- hypergrid foreign users control
* Grid -- maps map locations to IPs and regions
* Grid User -- grid-local information about users
* Inventory -- the inventory store
* Login -- the login service
* Presence -- tracks where in the grid user agents are
* User Accounts -- administrative info about users
* User Agents -- hypergrid local users protection

The simulators access these services through abstract interfaces, therefore being isolated from implementation details. The services are seamlessly instantiated as plugins in any process, namely ROBUST server shells and the simulators processes themselves, which means that we have complete reuse of service code between standalone and grid configurations. The plugin specification is done in configuration files (.ini). Moreover, access to remote services is also seamlessly achieved through the instantiation of stubs (aka service connectors) as plugins; again, the specification of which stubs the simulators use is done externally in configuration files (.ini).

This layering allows for alternative third-party implementations of the entire resource service infrastructure without having to affect one line of code in the simulator, and simply using different ini files. Starting in this release, there is an alternative infrastructure to Robust: [http://code.google.com/p/openmetaverse/ SimianGrid], a project separate from OpenSimulator. The standard OpenSimulator release includes simulator's connectors and configuration files for the SimianGrid, but that infrastructure is not distributed with OpenSim, only Robust is.

== Database changes ==

[[File:DB-0.7.jpg|400px|right|(click to enlarge)]]

[[File:DB-0.7-old-tables.jpg|400px|right|(click to enlarge)]]

The database schema has changed considerably from previous releases. The top picture on the right shows the entire set of tables for a clean installation of the 0.7 release with MySql. The bottom picture shows the new tables as well as the tables that existed in previous versions of OpenSimulator and that are now obsolete, stroked in red. OpenSimulator does not drop the old tables automatically, for obvious reasons. Once you are sure your data migration was successful, you can then drop the obsolete tables manually.

In the picture on top, the tables are grouped into 2 catalogs, the service-db and the simulator-db, corresponding to the data managed by the resource services (the ConnectionString under the [DatabaseService] section) and the data managed by the simulators (the connection_string under [Startup] section), respectively.

As before, you have a lot of freedom to define how the data is organized, so, for example you might have one single catalog with all the tables (like the organization shown in the picture on the bottom). In any case, after a clean installation of release 0.7, there should be all these tables in your DB.

For SQLite, the tables are split among several .db files under the bin directory. Here are the SQLite .db files that a clean install of 0.7 should produce:

$ ls -l *.db
----------+ 1 crista None 6555648 Jun 14 08:15 Asset.db
----------+ 1 crista None 564224 Jun 14 08:15 OpenSim.db
----------+ 1 crista None 5120 Jun 14 08:15 auth.db
----------+ 1 crista None 4096 Jun 14 08:14 avatars.db
----------+ 1 crista None 4096 Jun 14 08:14 friends.db
----------+ 1 crista None 4096 Jun 14 08:14 griduser.db
----------+ 1 crista None 26624 Jun 14 08:15 inventory.db
----------+ 1 crista None 0 Jun 14 08:14 inventoryStore.db
----------+ 1 crista None 4096 Jun 14 08:15 userprofiles.db

With SQLite, the simulator data is in OpenSim.db; the service data is in all the other files. inventoryStore.db has to do with migrations of inventory from older OpenSimulator releases; on a fresh install, this file is created but is has no data, you can safely delete it afterward.

== Hypergrid changes ==

The Hypergrid underwent considerable changes to make it more secure. 0.7 features HG1.5, an interoperability design that is as secure as it can be while continuing to assume the use of the regular Linden viewer. Here are the highlights with respect to security.

'''HG Teleports: The Gateway'''

HG teleports are now done through the Gateway service, as opposed to being done directly between the departing and the receiving simulators. The flow is like this: user U is in sim A of grid G1, and wants to HG TP to sim B of grid G2; sim A posts the user agent to the Gateway service of G2; after verifying a few things, and making sure this is a genuine agent for user U, the Gateway service in G2 logs in the user's presence in the local grid as a valid grid user, and posts the agent to sim B; sim B in G2 then contacts Sim A in G1 telling it it can delete the agent; at that point sim2 logs off user U from G1.

The posting of foreign agents directly to simulators of a grid, without passing through the Gateway, will fail.

In 0.7, the Gateway is still not performing authorization (i.e. access control for foreign users based on grid-specific policies), but that step is now possible, and will be introduced in a future release.

'''User Agents Verification'''

Prior to 0.7, it was possible to impersonate users by launching agents at simulators pretending to be those users. This vulnerability was independent of the Hypergrid being active or not, it affected all publicly available simulators. With 0.7 and beyond, and for grids where all simulators are under the same authority, this vulnerability has been eliminated.

HG1.5 includes pieces of protocol that guarantee that the user agent being launched at the Gatekeeper of a grid is indeed a genuine agent from the claimed user.

'''Inventory Access'''

The important thing to know about the family of viewers deriving from the Linden viewer is that they all access the user's inventory from the simulator that the user is currently on. In other words, they expect the simulators to proxy inventory, instead of accessing inventory directly from the user's inventory service. This poses serious security and privacy issues that can only be minimized but not eliminated. HG1.5 minimizes the risks as much as they can be minimized while allowing users to access their inventory everywhere. This comes at the cost of a slight UI mismatch at points.

First, in HG1.0, the visiting simulator had the power to delete items from the user's inventory and even delete the entire user inventory. That vulnerability has been eliminated. Foreign simulators cannot delete anything from the user's inventory: "purge" actions from a foreign simulator are ignored by the user's home inventory service. This means that if the user performs a genuine "purge" while in a foreign sim, the viewer will show that the items have been purged, but upon the next login those items will be in the Trash bin again, because they weren't really deleted.

Second, upon arrival at a foreign simulator that simulator is not given the user's root inventory folder. Instead, it is given another folder called Suitcase that will act as root folder while the user is visiting. As such, the simulator cannot recursively download the user's inventory; it can only 'see' the items and folder under the Suitcase folder. (No need to create a Suitcase folder, it will be created if it doesn't exist)

Besides the Suitcase folder, the only items that the simulator will know about upon user's arrival are those pertaining to the user's current appearance. 'Knowing about' means that a rogue simulator can copy them; but it can never delete them, as explained above.

Because inventory access is dictated by the viewer (i.e. by the user's actions), privacy of inventory depends on what actions the user does while visiting foreign grids. If the user does not access his/her inventory, the visiting simulator will know very little about it -- only the things stated above. On the other extreme, searching for an inventory item or opening up the texture picker makes the viewer query the entire user inventory, sending to the simulator all folder identifiers one by one; this means that the visiting simulator will 'see' the entire inventory; rogue simulators may then copy the items (again, they cannot delete them).

While using the Linden family of viewers, HG users should be aware of these issues. Trust decisions, ultimately, fall on them. If users trust the visiting grid, they can access their inventory without worrying that it will be stolen; if, however, the users don't know much about the simulator that they are visiting, they can still visit but should abstain from performing inventory actions.

== Groups Changes ==

The groups module can use a PHP XmlRpc server from:

* Flotsam project at http://code.google.com/p/flotsam/
* SimianGrid project at http://code.google.com/p/openmetaverse

The same GroupsServerURI configuration variable is used for either. 0.6.x setups using the old XmlRpcServiceURL configuration variable should be changed to use GroupsServerURI as illustrated in Opensim.ini.example.

== Profile Changes ==

The profile feature has been discontinued from the core distribution. 3rd-party addons provide different flavors of support for this feature.

== Bug Fixes, New Features and Assorted Changes ==

* Impovements to sculptmap and level of detail handling.
* Standalone database configuration simplified.
* Parcel and estate bans
* Neighboring regions being brought up and down results in correct accessibility in the connected clients.
* Friends online/offline notifications are now working across the board.
* Object attach/drop/attach correctly working.
* Inventory folder 'wear' working correctly.
* Inventory accept/decline notifications working correctly.
* Eliminated deadlock affecting scripts startup. This deadlock showed more often in certain mono versions. The same code was responsible for a CPU spike at region startup, which is now under control.
* Megaregion prims now in place after unclean shutdown. They used to be missing.
* Several permissions vulnerabilities fixed.
* Allow use of old angle rules PSYS_SRC_INNERANGLE and PSYS_SRC_OUTERANGLE in llParticleSystem().
* Bug fix in llRot2Euler()
* llVecNorm() now returns a zero-length vector when one is supplied as input.
* Fixed problem where "Adult" regions were reported as being of type "Unknown"
* Fixed Copy on Ray, Drag Copy and other little things.
* Make drag copy and copy-on-ray handle friends list perms properly.
* Added checks to XInventory DB layer to truncate names and descriptions, so they fit their sizes in the DB.
* Guarded prioritizer agains null values as those produced by a bullet dying before it can be updated
* Security fix: Allow only textures to be fetched using HTTP texture cap
* Fixed faulty profile cut parameter checking in llSetPrimitiveParams()
* Fixed attachments coming back upon being detached in neighbouring regions and crossing.
* Added CHANGED_TELEPORT event trigger upon inter-sim teleports.
* Prevented region crossings from screwing up complex attachments by preserving link numbers.
* Added ability to load IARs directly from URIs
* Added prim prioritization according to several schemes (configurable)
* Fixed spamming the assets table with map tiles.
* Corrected an invalid construction of Primitive.TextureEntry
* Added LightShare scripting
* Added SimianGrid connectors
* "Share with group" implemented for object inventory items. This only works if you're using a groups module with OpenSimulator.
* Added HTTP texture retrieval.
* Fixes to allow Linden Lab's viewer 2 to work, though some new features of this viewer (e.g. shared media/media on a prim) are not yet implemented.
* Added --skip-assets option to load oar command. This allows an oar to be loaded without loading its assets, which can be quicker if the assets are already known to be in the database.
* Various core performance improvements.
* Various core stability improvements.

* Master Avatar no longer in use. Upon creation of a new region, the user is prompted for the region owner and estate information. In standalone configurations, the region owner account is created if it doesn't exist; in grid configurations, the region owner account must already have been created.

= Upgrading from older releases =

Upgrading the database from older releases is done automatically when OpenSimulator 0.7 is first run; no special provisions are required. However, we very strongly recommend that you backup your database first, in case something goes wrong during the migration process.

Configuration files, on the other hand, have changed in 0.7 compared with 0.6 versions. Simply copying old configuration files can result in strange errors. We recommend that you start afresh with the OpenSim.ini.example and example files in bin/config-include and manually move accross any changes that you've made to the default configuration.

== Standalone Deployments ==

For standalones, there is no noticeable difference in the mode of operation. The main configuration file is OpenSim.ini, as before; make sure it exists and that is readable. If you are upgrading from 0.6.[7-8-9], you should already know about config-include/StandaloneCommon.ini. If you are upgrading from older releases, please be aware that this additional configuration file is needed. Make sure it exists and that it is readable. There are .example files for both of these.

There were several changes and additions to the configuration files. As such, it is better that you start with the given .example files and customize from them, as opposed to upgrading your existing ini files.

== Grid Deployments ==

The deployment model for grids has changed considerably, as explained before, so you need to acquire the know-how for operating in this post-0.7 model. The most important change is this: '''none of the UGAIM servers exist any longer'''; they have been replaced by one single server shell, Robust.exe, configured by one single configuration file, Robust.ini (or Robust.HG.ini). There are .example files provided. Copy one of them, and make the appropriate customizations. Robust does not depend on OpenSim.ini, only on Robust.ini.

Robust.exe -inifile=Robust.HG.ini
or
Robust.exe -inifile=Robust.ini

On the simulators' side, the operation is the same as before. The main configuration file is OpenSim.ini, as before; make sure it exists and that is readable. If you are upgrading from 0.6.[7-8-9], you should already know about config-include/GridCommon.ini. If you are upgrading from older releases, please be aware that this additional configuration file is needed. Make sure it exists and that it is readable. There are .example files for both of these.

It is better that you start with the given .example files and customize from them, as opposed to upgrading your existing ini files.

= Troubleshooting =

When migrations fail, the migration number is incremented anyway. If one of your migrations fail, notice which number it was, and to which table it pertained to. Then, login to the DB and set the version number of the corresponding store to the number just before the failed migration.

For example, if there is a failure in migration 8 for the assets table, issue this command in the DB:
> UPDATE Migrations SET version=7 WHERE name='AssetStore';
Then run Robust/OpenSim again.

The very last resort is to perform the migration manually, i.e. login to the DB server and issue the offending statement directly there.

See also [http://opensimulator.org/mantis/view.php?id=4875 this bug report] for useful tips related to account migration problems.

[[Category:Release Notes]]

Console-less OpenSim

2013-10-09T14:07:05Z

Joe Radik: /* Background */

__NOTOC__
{{Quicklinks}}
 
== Background ==
OpenSimulator uses consoles for each service it's running. It was already possible to run the services(UGAIMR) in the background, while still being able to access the consoles. On Linux we used the convenient screen tool for this. The ideal situation would be though, to run most commands from an external source like a webportal. The region service has an XMLRPC interface, that's called remote admin. While remote admin offers controls to some extent, it's still impossible to let's say shutdown the region service, and restart it from a webpage. This would require a seperate xmlrpc daemon, which has control over the OpenSimulator services. In python, it's quite easy to make such a xmlrpc daemon as you will see below.

== Concepts ==
XMLRPC is a powerful, yet simple protocol that's supported by most scripting languages. From all scripting languages, python has the best options to actually create a standalone daemon, that can handle remote xmlrpc calls. With such a standalone daemon, it's simple to link systemcommands to xmlrpc calls. Each simulator would have such a daemon, allowing the controling webportal(like WiXTD) to issue commands to each daemon. This would allow total control from a webportal, like service rebooting, rolling restarts, rolling updates, ugaim on/off, etc. Currently the code below doesn't have any security, but it can be extended to be really secure(SSL, host-based dispatching). It's focussed on a linux platform at the moment, but can be easily modified to work on a windows platform as well.

== MooRPC ==
This code is part of the moo-package on the forge. The script depends on the following custom libraries: [http://pycurl.sourceforge.net/ pycurl], [http://twistedmatrix.com/trac/ twisted], [http://www.jejik.com/articles/2007/02/a_simple_unix_linux_daemon_in_python/ daemon] and [http://www.voidspace.org.uk/python/configobj.html confObj]. It also uses linux-commands, screen and the directory-structure from Moo currently. You're free to modify the code.

== Source ==
<source lang="python">
#!/usr/bin/python
# MooRPC, XMLRPC controller for WiXTD
# BSD-Licensed
# Copyright (c) <2009>, <Jeroen van Veen, OS-Networks>
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
# * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# * Neither the name of the <organization> nor the
# names of its contributors may be used to endorse or promote products
# derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY <OS-Networks> ``AS IS'' AND ANY
# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL <OS-Networks> BE LIABLE FOR ANY
# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

from twisted.web import xmlrpc, server
from twisted.internet import reactor
import socket, os, sys, time, xmlrpclib, pycurl
import xmlrpclib, pycurl
import subprocess
sys.path.append("./lib")
from daemon import Daemon
from configobj import ConfigObj

try:
import signal
from signal import SIGPIPE, SIG_IGN
signal.signal(signal.SIGPIPE, signal.SIG_IGN)
except ImportError:
pass
try:
from cStringIO import StringIO
except ImportError:
from StringIO import StringIO

class CURLTransport(xmlrpclib.Transport):
xmlrpc_h = [ "Content-Type: text/xml" ]

def __init__(self, username=None, password=None):
self.c = pycurl.Curl()
self.c.setopt(pycurl.POST, 1)
self.c.setopt(pycurl.NOSIGNAL, 1)
self.c.setopt(pycurl.CONNECTTIMEOUT, 30)
self.c.setopt(pycurl.HTTPHEADER, self.xmlrpc_h)
if username != None and password != None:
self.c.setopt(pycurl.USERPWD, '%s:%s' % (username, password))
self._use_datetime = False

def request(self, host, handler, request_body, verbose=0):
b = StringIO()
self.c.setopt(pycurl.URL, 'http://%s%s' % (host, handler))
self.c.setopt(pycurl.POSTFIELDS, request_body)
self.c.setopt(pycurl.WRITEFUNCTION, b.write)
self.c.setopt(pycurl.VERBOSE, verbose)
self.verbose = verbose
try:
self.c.perform()
except pycurl.error, v:
raise xmlrpclib.ProtocolError(
host + handler,
v[0], v[1], None
)
b.seek(0)
return self.parse_response(b)

class OSAdmin(xmlrpc.XMLRPC):
config = ConfigObj('settings.ini')
radminhost = config['RPC']['radminhost']
radminpw = config['RPC']['radminpw']
radminGW = xmlrpclib.ServerProxy(radminhost,transport=CURLTransport())
def xmlrpc_admin_broadcast(self,message):
return self.radminGW.admin_broadcast({"password": self.radminpw, "message": message})
def xmlrpc_admin_create_region(self,region_id,region_name,region_x,region_y,listen_port,region_master_first,region_master_last,region_master_password,listen_ip,external_address,allow_alternate_ports,lastmap_uuid,lastmap_refresh):
return self.radminGW.admin_create_region({"password": self.radminpw,"region_id": region_id,"region_name": region_name,"region_x":region_x,"region_y":region_y,"listen_port":listen_port,"region_master_first":region_master_first,"region_master_last":region_master_last,"region_master_password":region_master_password,"listen_ip":listen_ip,"external_address":external_address,"allow_alternate_ports":allow_alternate_ports,"lastmap_uuid":lastmap_uuid,"lastmap_refresh":lastmap_refresh})
def xmlrpc_admin_delete_region(self,region_name):
return self.radminGW.admin_delete_region({"password": self.radminpw,"region_name": region_name})
def xmlrpc_admin_shutdown(self):
return self.radminGW.admin_shutdown({"password": self.radminpw})
def xmlrpc_admin_region_query(self,region_name):
return self.radminGW.admin_region_query({"password": self.radminpw,"region_name": region_name})
def xmlrpc_start_simulator(self):
os.chdir('/opt/opensim/simulator')
cmd = "screen -dmS simulator mono /opt/opensim/simulator/OpenSim.exe"
os.system(cmd)
def xmlrpc_ping_simulator(self):
try:
print self.radminGW.admin_simhealth({"password": self.radminpw})
except xmlrpclib.Error, v:
if str(v)[1:14] == "ProtocolError":
return 0
elif str(v)[1:14] == "Fault -32601:":
return 1
else:
return 0
def xmlrpc_stop_ugaim(self):
cmd = "screen -S user -p 0 -X stuff $'shutdown\n'"
os.system(cmd)
cmd = "screen -S grid -X -p 0 stuff $'shutdown\n'"
os.system(cmd)
cmd = "screen -S asset -X -p 0 stuff $'shutdown\n'"
os.system(cmd)
cmd = "screen -S inventory -p 0 -X stuff $'shutdown\n'"
os.system(cmd)
cmd = "screen -S messaging -p 0 -X stuff $'shutdown\n'"
os.system(cmd)
def xmlrpc_start_ugaim(self):
os.chdir('/opt/opensim/simulator')
cmd = "screen -dmS user mono /opt/opensim/simulator/OpenSim.Grid.UserServer.exe"
os.system(cmd)
time.sleep(4)
cmd = "screen -dmS grid mono /opt/opensim/simulator/OpenSim.Grid.GridServer.exe"
os.system(cmd)
time.sleep(3)
cmd = "screen -dmS asset mono /opt/opensim/simulator/OpenSim.Grid.AssetServer.exe"
os.system(cmd)
time.sleep(3)
cmd = "screen -dmS inventory mono /opt/opensim/simulator/OpenSim.Grid.InventoryServer.exe"
os.system(cmd)
cmd = "screen -dmS messaging mono /opt/opensim/simulator/OpenSim.Grid.MessagingServer.exe"
os.system(cmd)
def xmlrpc_ping_ugaim(self):
os.chdir('/opt/opensim/simulator')
cmd = "screen -dmS simulator mono /opt/opensim/simulator/OpenSim.exe"
os.system(cmd)
def xmlrpc_ping(self):
return 1
def xmlrpc_fault(self):
raise xmlrpc.Fault(123, "The fault procedure is faulty.")

class RPCDaemon(Daemon):
def run(self):
reactor.listenTCP(9996, server.Site(OSAdmin()))
reactor.run()

if __name__ == "__main__":
daemon = RPCDaemon('/tmp/rpcMoo.pid')
if len(sys.argv) == 2:
if 'start' == sys.argv[1]:
daemon.start()
elif 'stop' == sys.argv[1]:
daemon.stop()
elif 'restart' == sys.argv[1]:
daemon.restart()
else:
print "Unknown command"
sys.exit(2)
sys.exit(0)
else:
print "usage: %s start|stop|restart" % sys.argv[0]
sys.exit(2)

</source>

Performance

2013-10-09T14:03:37Z

Joe Radik: /* Monitoring Performance */

{{Quicklinks}}

= Introduction =
OpenSimulator performance is a very complex issue. Performance can be affected by any number of things, including the number of prims on a region, number of regions, number of avatars, network quality between server and viewer, network quality between simulator and grid services, etc.

We can break down performance considerations into

# Network issues (bandwidth and latency between viewer and simulator, between simulators and between simulator and grid service).
# Simulator issues (e.g. number of scene objects, number of textures, number of scripts).
# Grid issues (chiefly scaling services such as asset, inventory, etc to serve more simulators and users).

The biggest issues are probably network and simulator issues.

To run a simulator you must have good bandwidth (to download textures), good latency (so that movements are seen and actions processed in a timely manner) and good quality (so that random packet drops don't result in missed actions or other problems).

You must also be aware of your hardware's capabilities. The more scene objects, scripts and avatars you have, the more memory and CPU will be used.

Grid issues are less important until you reach larger grid sizes (e.g. over 60 simultaneous users).

= General Tips =

* Where at all possible, don't assume something is a performance bottleneck, measure it! You might think your asset database is large, for example, but even large asset database seldom cause real issues.
* Make as many objects phantom as possible. Phantom objects do not need to be tested for collisions with avatars and other objects, reducing physics frame time and increasing performance.
* Make as few objects subject to physics (e.g. falling under gravity, movable by other avatars) as possible. Physics objects need a lot more collision testing than ordinary non-phantom objects.
* It can be hard to perform measurement at the moment since not a lot of tools exist. However, one such is [[pCampbot]] which is bundled with OpenSimulator. This can instantiate a number of simultaneous libomv clients on a simulator that can take certain actions such as clicking things and bouncing aroud. Apects of it (e.g. appearance) are currently rather buggy and generate a lot of logging guff.
* If your avatars are twitching a lot or flying around uncontrollably, this is often a signal of dropped packets caused by network issues. For important packets, the simulator will retry the send 3 times but drop the packet after that. On the simulator console, the command "show queues" will indicate how many packets the simulator has to resend and the total number of sends. If the total resends is greater than 10% then this is a signal of network issues, at least between a particular viewer and the simulator. The problem may be at the user's end (e.g. a bad router being used over wifi, a badly performing ISP) which are difficult to do anything about!

= Monitoring Performance =

Gathering data to analyze performance issues is an evolving area. We can split this into [[client side monitoring]] and server side performance analysis. Server side performance analysis will involve OpenSimulator specific [[monitoring]] and general system tools (e.g. top on Linux to monitor which processes are taking up CPU/memory and more general monitoring tools such as Zabbix).

= Viewer Performance Topics =

Performance issues can be tackled on the viewer side as well as on the OpenSimulator side. This typically involves lowering viewer graphical settings (e.g. reducing viewer-side draw distance). See http://community.secondlife.com/t5/English-Knowledge-Base/How-to-improve-Viewer-performance/ta-p/1316923 for more information.

= Simulator Performance Topics =

== Hardware Requirements ==
Unfortunately, this is a very difficult question in light of all the factors mentioned in the introduction. Apart from network, the most important

===CPU===
We can say that OpenSimulator does not run well when it only has access to a single CPU core - you should regard a dual-core machine as the minimum.

An extremely approximate rule of thumb is to have one core per regularly used region, with the minimum of two above. So a 4 region simulator would need 4 cores. However, this assumes continuous use of those regions - one could probably get away with a higher core to region ratio if those other regions were much less used (or not used simultaneously).

===Memory===
As a rule of thumb, a region with lots of avatars, 15000 or more prims and 2000 scripts may require 1G of memory. So a simulator with 4 such regions may require 4G. One could use less memory if not all regions will be occupied with avatars simultaneously, or where the are fewer scripts, for instance.

===Disk===
At the simulator level, storage performance is not a big issue unless one has scripts which need extremely high performance in rezzing and derezzing objects. Even in this case, 7200 rpm 3.5" desktop drives are generally sufficient - problems only start to arise with lower performing drives, such as those found in laptops.

At the grid level, faster storage may be useful when handling large numbers of asset, inventory or other service requests.

===Network===
Download and upload bandwidth and latency are important. The biggest use of upload bandwidth (from the server point of view) is to provide texture data to viewers. So a home network with poor bandwidth (e.g. 384 kbits up) will result in a poor experience for viewers, at least until they have received all texture data. So the requirement for upload bandwidth peaks when a viewer enters a region for the first time or after clearing their asset cache. The amount of bandwidth required will vary heavily with the number of textures on the region. An extremely approximate rule of thumb is to have 500 kbit per simultaneously logged in avatar.

The biggest use of download bandwidth (from the server point of view) is to continuously receive movement messages from connected avatars. However, in comparison to texture download, the bandwidth required is trivial - an approximate rule of thumb is 50 kbit per avatar.

Latency is critical on both upload and download to the simulator, since any delay will affect avatar movement packets (download to server from viewer) and updates to the viewer about other object/avatar position changes (upload from server to viewer). It's much harder to give advice here, though pings of greater than 350 milliseconds will start to degrade the user's experience on moving their avatar.

===Examples===
Below are some examples of hardware people use/have used. Please feel free to add to the list, or to add any reports to the performance studies and blog posts section. '''These are examples to help you in your selection, not recommendations.'''

Object Parts ~= # prim

Sensors and Timers are generally more intensive then regular scripts, so please specify quantity of each.

{| border="1"
!Description
!Operating System (please add Mono version if appropriate)
!OpenSimulator version
!RAM/AVG_USE_%
!CPU
!#/type of regions
!# simultaneous avs
!#scripts/timers/Sensors
!Location
!#objectparts
|-
|hosted Xen VPS
|Ubuntu Intrepid (8.10)
|Unknown
|540MB/?
|1x quad-core 2.5GHz Xeon (L5420)
|1 region + 9 voids
|generally 1-2
|few
|Knifejaw Atoll & surrounding on OSGrid
|?
|-
|hosted Xen VPS
|Ubuntu Jaunty (9.04)
|Unknown
|360MB/?
|2x dual-core 2.0GHz Xeon (5130)
|1 void
|generally 1-2
|none
|Knifejaw Road on OSGrid
|?
|-
|Dedicated Server from A+
|Windows Server 2003
|Unknown
|1 Meg
|1x single-core 2.8GHz Celeron
|2regions per server
|6 at once with no issues
|Waterfalls, texture anims, window texture switchers, lots of sound loops
|Pleasure Planet Welcome center & Region Pleasure Planet in OSGrid
|20000 prims per region
|-
|Amazon EC2 "high-CPU medium instance" (Xen VM)
|Windows Server 2003
|Unknown
|1.7GB
|1x dual-core 2.3GHz (Intel E5345)
|1 region with sailing race course
|7 avs, 4 in boats
|scripted start line
|Castle Rock, OSGrid
|
|-
|Dedicated Server from simhost.com
|SuSe 11.2 x64
|Unknown
|8gb / 50%
|4x Core2Quad Q9300 2.6ghz
|1 region (Wright Plaza) uses approx 4gb ram
|20-25 users
|Freebie Stores / Meeting Center / Video Theater
|@osgrid.org Heavy Use Sim
|17500 prims aprox 1500 scripts
|-
|Home machine
|Windows XP SP3
|0.7.0.1 (Diva r13558)
|3GB / 15-40% incl. Opensim and MySQL
|4x Core2Quad Q6600 2.4 GHz. Use: generally, 0-10%
|11 regions
|1-6 users
|Many scripted objects (1934 scripts)
|[http://zonjacapalini.wordpress.com/2010/08/25/condensation-land-a-status-report/ Condensation Land]
|38,065 prims
|-
|Home machine
|Ubuntu Lucid 10.04 (32 bit pae)
|0.7.0.1 (Diva r13558)
|160Mb no users, add 5Mb/user incl Opensim and MySQL
|I7-920 (dual threaded quad core), 3.8Ghz, 6Gb RAM, 0-10% Load
|4 regions (Diva default config)
|1-4 users (approx 20Kb/sec bandwidth/user)
|Few scripted objects (<10)
|[http://mars-simulator.hobby-site.org:9000/wifi Mars Simulation]- Based on [http://metatek.blogspot.com/2010/06/mars-simulation-for-distribution.html Erik Nauman's Open Blackboard]
|158 prims
|-
|Hosted Dedicated OVH
|Suse 12.2
|0.7.0.2 (D2)
|420Mb total, incl OS, Opensim and MySQL
|i7 Quad 950 (Bloomfield) 3.07GHz, 8 Core, 24Gb RAM, 0-1% Avg Load
|16 regions (4x4 mega-region)
|<6 users
|vehicle scripted objects (<5)
|[http://metaversesailing.com:9000/wifi Metaverse Sailing]
|<1000 prims
|-
|VPS
|Debian Lenny 5 (mono 2.4.2.3)
|OSgrid 0.7.1 (Dev) cd4d7a7: 2010-10-15
|655MB average out of 1722MB RAM, incl. MySQL
|Intel Quadcore 2.5 Ghz (1 core assigned to vps) average use: 40-45%
|20 regions
|<4 users
|about 20 different light scripts, but we're also experimenting with heavier HUD scripts (timers, lots of ll(Get/Set)PrimitiveParams and large lists) and custom IRC relay
|Phoenix Rising Isles on OsGrid
|3727 prims
|}

== Database ==

By default, OpenSimulator is configured to use the SQLite database. This is very convenient for an out-of-the-box experience since it requires no configuration. However, it's not designed for heavy usage, so if you build very quickly or have more than a few people on your simulator then you will start to see performance issues.

Therefore, we recommend that you switch to MySQL as soon as possible. This will provide a much better experience but will take a little bit of work to set up.

Unfortunately, tools for migrating OpenSimulator SQLite data to MySQL are currently limited. Migration is also possible by saving OARs/IARs of your data from sqlite and loading them up once you've reconfigured to use MySQL.

There is also a database plugin for MSSQL but this is not well maintained between OpenSimulator releases.

In standalone mode, both services and the simulator itself can use SQLite. In grid mode, SQLite is only supported for simulator data - the ROBUST instances must use a MySQL (or MSSQL) database.

In general a single MySQL instance for the ROBUST services instance will serve small, medium and even large grids perfectly well - it's a configuration that's widely used for even quite large websites.

== Configuration tweaks ==

There are a couple of OpenSimulator configuration tweaks that you can do to significantly improve script loading performance in certain situations. These tweaks can be made in your OpenSim.ini config file. These apply to current OpenSimulator development code (0.7.3-dev) and may also apply to 0.7.2, though certainly not any earlier.

===Set DeleteScriptsOnStartup = false===

[XEngine]
DeleteScriptsOnStartup = false

This means that OpenSimulator will not delete all the existing compiled script DLLs on startup (don't worry, this setting doesn't touch the actual LSL scripts in your region). This will significantly improve startup performance. However, if you upgrade OpenSimulator in place (e.g. you regularly update your installation directly from development code) then you may occasionally see problems if code changes and your previously compiled DLLs can't find their old references.

In this case, you can either set DeleteScriptsOnStartup = true for one restart in order to clean out and recompile script DLLs or you can manually delete the relevant bin/ScriptEngines/<region-uuid>/*.dll.* files, which will force OpenSimulator to recompile them. You could also delete the entire bin/ScriptEngines/<region-uuid> directory but this would lose all persisted script state (which is kept in the <script-item-id>.state files).

===Set AppDomainLoading = false===
[XEngine]
AppDomainLoading = false

By default, OpenSimulator loads every script DLL into its own AppDomain. If this is set to false, then all scripts are loaded into OpenSimulator's default AppDomain instead.

This will significantly improve script startup times and reduce initial per-script memory overhead.

However, setting this to false will also prevent derezzed script DLLs from being removed from memory (only whole AppDomains can be unloaded). This might cause an OutOfMemory problem over time, as avatars with scripted attachments move in and out of the region. Whether this is a problem for you will depend on factors such as the avatar population of your grid.

In addition, Windows users have reported script loading problems with AppDomainLoading = false, though I (justincc) haven't been able to replicate this with current OpenSimulator code on my WindowsXP machine.

= Grid Performance Topics =

Scaling a grid is a complex task and only for the very technically inclined. It is also an area under active investigation. The advice below will change considerably over time as OpenSimulator and its environment changes and we learn more about perfomrnace issues.

When would you start to meet grid scaling issues? As an extremely rough and really quite arbitrary and pessimistic rule of thumb, you will probably start to have to think about things when you exceed 50 regions containing a large number of prims or 50 simultaneous users with large inventories. But this will very a tremendous amount depending on your situation. If you have thousands of regions with very few prims that much more supportable than 50 regions with 45000 prims each.

You are likely to encounter issues in two areas - database and services.

== Database ==

=== Assets ===

==== The problem ====

Due to the architecture of distributed architecture of OpenSimulator, where regions are running on a number of different machines over a network, it's extremely hard to identify assets that are not in use and hence can be deleted. Equally, the fact that assets are immutable leads to continual growth in the asset database.

In theory, one could identify unused assets if one could identify all references in simulators and in user inventory. However, this is extremely hard to do where machines are distributed over a network. If a grid only has a few simulators all running on machines that are controlled by the same entity running a grid, then it becomes a little more tractable but even then would almost certainly involve significant downtime. For stand-alone grids, or for environments where assets are not passed between grids (ie: giving a texture to a friend on another grid) [http://was.fm Wizardry and Steamworks] provides an experimental script that will do exactly that. It is currently available at the [http://was.fm/opensim:database:asset_cleaner asset cleaner] project page and published under an MIT license.

Asset deletion would be easier for a one simulator grid or a standalone. However, even code to implement asset deletion on standalones has not yet been implemented and would certainly require significant simulator downtime.

A promising area of research involves improving OpenSimulator's recording of asset access times (e.g. recording access periodically). Then assets which aren't accessed for a long time (e.g. a year) could be deleted or moved to cold storage (e.g. DVD). One is left with the problem of not deleting assets permanently cached by simulators but perhaps this could be solved by the simulators occasionally 'pinging' the asset service with notification of what assets they cache.

Another step to reduce asset database size is to eliminate duplicate assets by hashing. There is [[Deduplicating Asset Service|an experimental development asset service]] for this. Third party services such as [[https://github.com/coyled/sras SRAS]] also do this.

==== Possible solutions ====

* If you run a grid for yourself or, if you run a grid where you do not give away your content, then the [http://was.fm/opensim:database:asset_cleaner asset cleaner] from [http://was.fm Wizardry and Steamworks] may be a good solution to track down stray assets and delete them from the database automatically. It is based on dumping OARs and IARs, as per the second option in this section, but after dumping them, it automatically performs the search for you and prompts you to delete several supported assets. Current development is going towards automatically exporting OARs and IARs from PHP so that the procedure is made seamless.

* Save every region to an OAR and every user's inventory to an IAR. We believe this is equivalent to finding all referenced assets and can be done manually. However, it's very laborious for installations with a large number of users and requires grid downtime. Tools could be written to improve this, particularly in systematically saving all user inventories to IARs.

* Do nothing. MySQL can store a very large amount of data before encountering issues - it's used for extremely large websites and other applications after all. This assumes you have the disk space.

* Use an external asset service such as [[https://github.com/coyled/sras SRAS]]. SRAS, in particular, is a third party asset service that does deduplication, asset compression, and stores assets on disk rather than in a database. It also has some nice features like preventing assets being served without deleting them. It's used by OSGrid, for instance. However, it does work in a different way from the bundled OpenSimulator asset service (e.g. backup of on-disk assets involves some extra steps compared to just backing up a database). It also requires a migration step that may take a considerable time if you have an existing asset collection.

=== Other databases ===

The space required by assets far outweighs other data storage requirements so only asset data is generally an issue.

== Services ==

=== The problem ===

The other problem is with handling the number of requests to services when the number of simulators and users grow. The asset service isn't generally a problem since simulators cache all assets used, though it can form a bottleneck on OAR upload. The biggest issue is generally caused by users, chiefly due to inventory access and perhaps update last user positions in the GridUser service (and database table).

ROBUST uses an embedded [[http://webserver.codeplex.com/ C# HttpServer]]. Performance comparisons to other Webservers (e.g. Apache) have not been carried out (?) but responses appears to be much, much slower. As it has been discontinued it's also rather unlikely to have it's performance improved. In future, OpenSimulator may embed a different HTTP server but this is extremely unlikely in the short term.

=== Possible solutions ===

* Split up services. By default, ROBUST runs every service in one process. However, because services are separate from each other, you could run some services (e.g. inventory in one ROBUST instance and other services (e.g. asset) in a different instance, even if they both point to the same database. Because the embedded C# webserver is slow and possibly not very concurrent, this can achieve significant performance improvements even if all ROBUST instances are running on the same machine.

* Instantiate extra ROBUST copies of problem services (e.g. inventory). Because services are stateless (akin to a webservice), you can load balance requests between multiple instances using a reverse proxy such as nginx. Again, because the embedded webserver is probably inefficient, you can achieve performance improvements by running multiple copies of services on the same machine.

* Use an external service based on a more efficient HTTP server, e.g. [https://github.com/coyled/sras SRAS] (asset service only) or [http://code.google.com/p/openmetaverse/ SimianGrid]. Please be aware that SimianGrid uses a different set of simulator <-> service protocols than used by ROBUST. The necessary SimianGrid adaptors are part of the core OpenSimulator distribution.

* Write your own services to run on an external webserver. This wouldn't be too hard to do in something like PHP, though one would need to work out the currently undocumented wire formats. If you do this, please do let us know :)

= Performance studies and blog posts =

These provide some interesting data on the performance limitations of OpenSimulator at various points in time.

* [https://lists.berlios.de/pipermail/opensim-users/2010-August/005189.html https://lists.berlios.de/pipermail/opensim-users/2010-August/005189.html] - Some interesting information from Mr Blue. Physical objects and max avatars are limited by single thread performance in OpenSimulator.
* [http://www.sciencesim.com/wiki/doku.php/vwperf/start http://www.sciencesim.com/wiki/doku.php/vwperf/start] - Links to ScienceSim performance studies, including some very recent ones.
* [[Improving Performance]] - An old page from July 2009 detailing some performance issues on OpenSimulator. Some of these issues are still valid (e.g. ODE issues).
* [[NHibernate Performance Testing]] — SQLite and MySQL performance tests with NHibernate.
* [[LibSecondLife performance problems]] - Another old page from November 2007 detailing issues with libsecondlife (now called libopenmetaverse).
* [http://opensim.cybertechnews.org/?p=71 Experiences from Operating a 3D Region Server in OSGrid - Part 1]
* [http://opensim.cybertechnews.org/?p=104 Experiences from Operating a 3D Region Server in OSGrid - Part 2]