Introducing OpenSim Inventory Archives (IARs)

(Updated Thursday 24th September 2009) – IAR load and save works again on grid mode again as of revision e1abc3 (also on this day)).  However, the user service also needs to be of this revision or later.

(Updated Friday 18th September 2009 – unfortunately it turns out that the added password requirement stops load and save iar working in grid mode.  A fix will come soon).

(Updated Tuesday 15th September 2009 since load iar and save iar commands also need the user’s password as of Git revision c5455d4 on the same day).

Some time ago I mentioned that I was working on a feature for OpenSim known as Inventory ARchives (IARs).  Well, after a longer period than I would have liked, this facility is now available on an experimental basis in the latest bleeding edge OpenSim code.

What is an IAR?

The short answer is that an IAR is the inventory equivalent of an OpenSim ARchive (OAR).

The long answer is that inventory archives are a way of saving selected inventory folders and items to an external file.  This file can then be reloaded later on or given to somebody else to load onto a completely different installation of OpenSim.  The IAR contains all the data necessary to fully restore the items, including textures, scripts and other contained assets.

The IAR facility isn’t intended to supplant tools such as Second Inventory, which extract and restore objects via the client interface.  Rather, it exists as a way for region owners (whether standalone or on a grid) who have access to the region console to backup and transfer inventory.

IAR is also a something of a rough and ready format.  Like OAR, it relies on undocumented object serializations.  It will also itself be subject to considerable evolution in the future.  Nonetheless, I intend that IAR formats will be backward compatible – IARs saved now should remain loadable into future versions of OpenSim.

How do I use an IAR?

IARs are loaded and saved from the region console, just like OARs.  Before doing any loading or saving, you have to be logged in to a region served by the region simulator.

Let’s run through an example.  Suppose that you have an inventory structure like so

and you want to save the contents of folderA to an IAR.  On the region console command line you would issue the command

save iar Justin Clark-Casey folderA userpassword

with your own avatar name and password instead of mine, of course   This would save folderA and its descendant folders to a file called user-inventory.iar.  If you want to specify a different filename then you can add it to the end of the command, for example

save iar Justin Clark-Casey folderA userpassword my-great-items.iar

If you need to specify a folder or item containing spaces, then you’ll need to surround the path with quotes (e.g. “Folder A” or “Folder X/Folder Y”).

Having saved the IAR, you decide that you’d like to make your items available to the world so you put the file on a website.  John Does comes along and thinks that your items sound really interesting, so he downloads the IAR to the bin/ directory of his own OpenSim installation, starts OpenSim up and logs in.

Now, let’s suppose that John has an inventory structure like this

and he wants to load the IAR into folderY in folderX.  To do this he issues the command

load iar John Doe folderX/folderY userpassword my-great-items.iar

on the region console.  After a short delay the items appear in his inventory ready for rezzing!

Example IAR

Here’s an example IAR (containing the inventory folders and items described above) that you can download and load into your own bleeding edge copy of Git-fresh OpenSim (since revision 5a64ca on 14th September 2009).  If you’d rather not suffer the pain of the bleeding edge, then the load and save IAR commands will be active in the next OpenSim release (which should be 0.6.7).  Load and save IAR commands are present in OpenSim 0.6.6 but they were not complete in this version and do not work properly.

Final Notes

The load and save IAR feature is currently experimental.  Bug reports and suggestions for improvement are welcome!  The best place for bug reports is OpenSim’s Mantis system and the best place for suggestions right now is as comments on this blog post.  Thanks!

There is also some more information on the load and save iar commands on the opensimulator.org IAR page.

Next time…

On my next post (hopefully coming soon), I’m going to talk about some of the current limitations of the IAR implementation and what can be done about these in the future.

One thing that I do want to mention right now is that due to technical limitations item creator names are not preserved unless a profile for that name exists on the target OpenSim system.  I’ll write some more about this problem (and suggestions for overcoming it) on my next IAR post.