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 .inis under bin/config-include).

Users and distributors of OpenSim 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: SimianGrid, a project separate from OpenSim. The standard OpenSim release includes simulator's connectors and configuration files for the SimianGrid, but that infrastructure is not distributed with OpenSim, only Robust is.

Database changes

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 OpenSim and that are now obsolete, stroked in red. OpenSim 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 OpenSim 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 the to 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.

Bug Fixes

• 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.

Before you upgrade

Release 0.7 is using a newer MySql driver. Newer is better in general, but, unlike the previous one, this driver is unforgiving of poor configurations of your MySql server. So, before you actually install 0.7, it is advised that you do the following things:

• Increase the MySql server timeouts to huge numbers. This is done in your MySql configuration file. Note that this is unrelated to the configuration files of OpenSim or Robust -- if you don't know where the configuration file of your MySql installation is, please Google for it. Once you find it, edit it and set, for example:

[mysqld]

open-files-limit = 20000
interactive_timeout = 1000000
wait_timeout = 1000000
max_connections = 2000

Previous values as provided by Diva - to be confirmed these are wrong before deleting this part of the Wiki?
[mysqld]

open-files = 20000               (should be open-files-limit)
interactive_timeout = 10000000   (value range is to 2100000)
wait_timeout = 10000000          (value range is to 2100000)
max_connection = 2000            (should be max_connections plural)

• For details of MySQL system variables and their legitimate values, see [1]

• If your DB is accessed from machines other than localhost, add an entry in the hosts file of your DB server machine for every single machine that accesses the DB remotely. This new driver makes the MySql server perform reverse IP lookups, and it seems like it only looks in the hosts file and nowhere else.

Upgrading from older releases

Upgrading from older releases is done as usual; no special provisions are required. However, the configuration files have changed, and you need to pay close attention to them.

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.

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.

If you continue to encounter problems, try using the old MySql driver, which can be found in any of the 0.6.x releases. The file is called MySql.Data.dll. Place it in your bin, clean the directory, and build 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.