Installing 3rd party addins

Latest revision as of 11:33, 4 January 2015

This page explains how to install, update and uninstall 3rd-party addins for the simulator server in a systematic way. 3rd-party addins are packages created around binary distributions of region modules, possibly with additional external libraries and resources, that extend the simulator with additional functionality. Note that 3rd-party addins here refers to binary packages of OpenSim extensions; this is different from extensions available as source code, which you may already be familiar with, and for which you may already have a process in place for building and deploying into your grid. 3rd-party addins give the providers the option to keep the source code proprietary, and give you a relatively simple process for integrating those extensions into your installation of OpenSim and to evolve them in relative independence from updates to OpenSim core.

If you are a developer looking for information about how to develop and distribute addins, please see this other page.

[edit] Registry Location

Before you start using managed addins, it is important that you think carefully about where you want to keep these addins. Internally, OpenSim uses its own addins, and it installs the addin database under its bin folder. If you don't change anything, 3rd-party addins will be placed there too. Depending on what process you have in place for updating OpenSim, this may cause you trouble: if your process includes deleting the entire bin folder and replacing with a new one, that process will also delete your 3rd-party addins, and you will have to reinstall them again every time you update OpenSim core.

The location of the addin registry is given by a configuration variable in OpenSim.ini:

 [Startup]
     ...
     ;RegistryLocation = "."
     RegistryLocation = "/path/to/my/registry"

You can change it to point to another path in your file system. This location will be important for addin installation.

From here on, all the steps described next use the Mono Addins command line tool mautil. mautil allows us to package, distribute, install and uninstall mono addins for .NET applications in general.

[edit] Configuration Location

Another issue you need to think about is where to store the addins' own configuration files. This is important because as you update OpenSim or the addins, you don't want to have to reconstruct these configuration files over and over again.

The location of the addin configuration files is given by a configuration variable in OpenSim.ini:

 [Startup]
     ...
     ;ConfigDirectory = "."
     ConfigDirectory = "/path/to/my/addin/configs"

You can change it to point to another path in your file system. This location will be important for addin installation.

[edit] Initial Registry Update

Also before installing any 3rd party addins, you need to populate the registry with OpenSim's own addins, which are required for the installation of 3rd-party's. Do that by running this command in OpenSim's bin folder: (note: if you are in Linux, precede the command with mono)

 $ mautil.exe -reg /path/to/my/registry reg-update

For example:

 $ mautil.exe -reg C:/addins-registry reg-update

IMPORTANT: you need to issue these commands from the bin folder. Otherwise you need to add the -p parameter and set it to the directory where OpenSim.exe resides. So if you run mautil.exe from somewhere else, make sure to adjust that argument's value. For example, if you run it from the OpenSim root folder, the command above should be:

 $ bin/mautil.exe -p bin -reg C:/addins-registry reg-update

You can also use absolute paths, if that makes it easier.

From here on we will assume that mautil.exe is ran from OpenSim's bin folder, so we omit -p.

[edit] 3rd Party Repositories

The next step is to add remote repositories of addins to your OpenSim installation. There is no central repository of addins for OpenSim. Remote repositories are provided and maintained by 3rd parties, and you will have to find out about them by some means. You can add as many repositories as needed. To add a repository, run these commands in OpenSim's bin folder: (note: if you are in Linux, precede the command with mono)

 $ mautil.exe -reg /path/to/my/registry rep-add repo_url
 $ mautil.exe -reg /path/to/my/registry rep-update

For example:

 $ mautil.exe -reg C:/addins-registry rep-add http://metaverseink.com/repo
 $ mautil.exe -reg C:/addins-registry rep-update

Or if you decided to use the default OpenSim's bin folder as the registry location:

 $ mautil.exe -reg . rep-add http://metaverseink.com/repo
 $ mautil.exe -reg . rep-update

Again, if you run mautil.exe from somewhere else, make sure to use -p properly.

From here on you can check what addins are available by typing

 $ mautil.exe -reg /path/to/my/registry list-av

[edit] Installing Addins

Finally, you can install an available addin with the following command:

 $ mautil.exe -reg /path/to/my/registry install addin

For example, to install the most recent version of Diva.AddinExample:

 $ mautil.exe -reg C:/addins-registry install Diva.AddinExample

To install a specific version:

 $ mautil.exe -reg C:/addins-registry install Diva.AddinExample,0.8.1.0.1

The installed addins are placed under /path/to/my/registry/addins/addin. Often, these addins will bring a configuration (.ini) file that you may need to change. Depending on how the addins are coded, they may or may not copy their own configuration file to the folder specified above, ConfigDirectory. Even if they do, they can only do it when OpenSim runs the addins the first time. So, the best practice is for you to go to the directory where your addin was installed and copy the ini file from there to your own ConfigDirectory.

For example, for this particular AddinExample, you would be able to find its configuration file in

 C:/addins-registry/addins/Diva.AddinExample.0.8.1.0.1/AddinExample.ini

You would then copy it to /path/to/my/addin/configs and edit it there.

[edit] Checking for, and Installing, Updates

To check:

 $ mautil.exe -reg /path/to/my/registry list-update

To update:

 $ mautil.exe -reg /path/to/my/registry update addin

[edit] Uninstalling Addins

 $ mautil.exe -reg /path/to/my/registry uninstall addin

For example:

 $ mautil.exe -reg C:/addins-registry uninstall Diva.AddinExample

[edit] Versioning

One important aspect of installing and managing 3rd-party binary components is the issue of versioning. .NET, in particular, is quite strict about interface compatibility between libraries, and it will complain (by raising exceptions or by crashing) if an executable tries to link an incompatible library. In the case of 3rd-party addins, incompatibilities may happen when those addins have been compiled against a version of OpenSim that is different from the one you have. Some of those incompatibilities will be caught at the time of addin installation, but some will not -- these latter ones may show up when you run OpenSim.

For example, suppose that the latest MISearchModules addin was compiled against OpenSim 0.8.1.0 and you have OpenSim 0.7.6.2. When you try to install that addin, the addin installation will fail, because MISearchModules,0.8.1.0.1 has an explicit dependency on OpenSim 0.8.1.0. Since your OpenSim version is older than the addin, the incompatibility will be detected, and the installation will fail. In this case, you would need to find and install the older MISearchModules addin for OpenSim 0.7.6.2.

The most problematic situation is the one in reverse. Suppose that you have installed MISearchModules,0.7.6.2.1 (which had been compiled against OpenSim 0.7.6.2), and that you update your OpenSim installation to OpenSim 0.8.1.0. The mono addins framework will deem this addin compatible with the new version of OpenSim (because the new OpenSim version is higher than the addin's). But in reality, the new OpenSim dlls may have different .NET interfaces than those against which the MISearchModules addin was compiled. When the addin uses parts of core OpenSim that have changed between versions, a failure may happen when you run OpenSim -- it may be just an exception in the log or a complete crash of the simulator. In this case, you would need to find the newer version of the MISearchModules addin for 0.8.1.0 (see check for updates above). If it doesn't exist yet, you need to uninstall the MISearchModules addin (see uninstalling addins above) until the newer version becomes available by the provider of that addin.

Version numbers of all kinds are mainly annotations for people. The ground truth is always in the binary signature of dlls.

Here are some concrete examples:

• Addin Foo requires OpenSim 0.8.1, and is being installed in OpenSim 0.8.1 ==> Addin compatibility ok. Binary compatibility likely ok.
• Addin Foo requires OpenSim 0.7 and is being installed in OpenSim 0.8.1 ==> Addin compatibility ok. Binary compatibility likely will fail, depending on a number of things. If Foo has been compiled against OpenSim 0.7, then it will surely fail, because the OpenSim APIs tend to change substantially between releases. But if Foo was compiled against 0.8.1, but the developers of Foo forgot to update the declared dependency, then binary compatibility will be ok, and the plugin will be successfully installed.
• Addin Foo requires OpenSim 0.9.0 and is being installed in OpenSim 0.8.1 ==> Addin compatibility will fail. Foo won't even get to run to check binary compatibility.