Installing 3rd party addins

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 region modules, possibly with additional external libraries and resources, that extend the simulator with additional functionality.

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.

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 -p . -reg /path/to/my/registry reg-update

For example:

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

The argument to the -p parameter, in this case '.', needs to be 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.

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 -p . -reg /path/to/my/registry rep-add repo_url
 $ mautil.exe -p . -reg /path/to/my/registry rep-update

For example:

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

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

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

Again, the argument to the -p parameter, in this case '.', needs to be the directory where OpenSim.exe resides. So if you run mautil.exe from somewhere else, make sure to adjust that argument's value.

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

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

Installing Addins

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

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

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

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

To install a specific version:

 $ mautil.exe -p . -reg C:/addins-registry install Diva.MISearchModules,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 edit. If that's the case, find that file, and edit it there in /path/to/my/registry/addins/addin; do not copy or move these configuration files anywhere. They will be read from their locations.

Checking for, and Installing, Updates

To check:

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

To update:

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

Uninstalling Addins

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

For example:

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