Inventory Archives
From OpenSimulator
Contents |
Introduction
OpenSim Inventory Archives (IARs) are a means by which inventory folders and items can be saved offline to a single file (an IAR). This file can then be loaded into a different OpenSim installation.
Like OpenSim_Archives, IARs save all the necessary asset data required to fully restore the items including textures, sounds, scripts and objects contained in the inventory of other objects.
IARs have been enabled in OpenSim since Git revision 5a64ca (OpenSim 0.6.7 and later).
Usage
IARs are saved and loaded from the region console. Before performing either of these operations the user that owns the inventory to be used must be present in one of the regions run by the region simulator. You may log off after the save or load operations are initiated, not necessary to stay inworld.
save iar
The command to save an IAR on the region console is
save iar <user name> <path> <password> [-profile=<url>] [<filename>]
where
- <user name> is the name of the user to save inventory from
- <path> is the path to an inventory item or folder. If the path is for a folder, that folder and all its contents (both descendant folders and items) are saved. If the path is for an item, then only that item is saved.
- <url> is the URL of this world's profile service. It is not required that the profile service is operational; the information will still be saved, and it will be displayed wherever the archive will be loaded.
Components of the path are separated by a forward slash ("/"). If you need to specify a path with spaces, you can surround the whole thing with double quotation marks (e.g. "Folder A/Folder B").
You can specify that the contents of a folder should be saved rather than the folder itself using the * wildcard. For instance, "/*" will save your entire inventory but not the "My Inventory" folder itself. This can be useful if you want to restore a saved inventory to an existing one using the load iar --merge function discussed later on.
If a name or folder contains a forward slash ("/") then it can be escaped with the backslash (i.e. "\/") to stop it being seen as a path separator. Back slashes themselves need to be escaped with another backslash (i.e. "\\").
One further issue here is that it's not possible to distinguish between identically named folders or items on the path - the workaround is to rename your items/folders if you need to specify them in the path :)
- <password> is the password of the user.
- <filename> is an optional filename for the IAR. If none is supplied, then the filename user-inventory.iar is used in the current directory. I recommend that iars have the .iar extension.
Examples
Here's an example. Suppose you have an inventory structure like this
My Inventory
|
+-- FolderA
|
+-- FolderB
| |
| +-- ItemX
|
+-- ItemY
If you type
save iar John Doe FolderA PASSWORD my-items.iar
then FolderA and everything in FolderA (FolderB, ItemX and ItemY) will be saved into an IAR called my-items.iar. On the other hand, if you type
save iar John Doe FolderA/FolderB/ItemX PASSWORD my-items.iar
then only ItemX will be saved.
With save iar you can save your entire inventory as well as the contents of particular folders or individual items.
For instance, typing
save iar John Doe / password
would save your entire inventory to user-inventory.iar (since no filename was given).
load iar
An IAR can be reloaded to an OpenSimulator instance with the load iar command
load iar <user name> <path> <password> [<filename>]
where
- <user name> is the name of the user to whom to load the inventory
- <path> is the path to which the IAR should be loaded. This has to be a folder which already exists in "My Inventory". See the save iar command for more details.
- <password> is the password of the user.
- [<filename>] is an optional filename for the IAR. If none is specified, then the filename is assumed to be user-inventory.iar in the current directory.
Examples
Suppose that "David Hume" has recieved the my-items.iar saved above containing FolderA, FolderB, ItemX and ItemY. David Hume already has an inventory structure like this.
My Inventory
|
+-- Folder1
|
+-- Folder2
|
+-- Folder3
David wants to load the IAR to Folder3, so on the region console he executes
load iar David Hume Folder1/Folder3 password my-items.iar
After a little while he ends up with the folder structure
My Inventory
|
+-- Folder1
|
+-- Folder2
|
+-- Folder3
|
+-- FolderA
|
+-- FolderB
| |
| +-- ItemX
|
+-- ItemY
where ItemX and ItemY are ready for rezzing.
From OpenSim 0.7 and onwards, you can also load IARs directly from web addresses. For example
load iar Betrand Russell Folder2 PASSWORD http://justincc.org/downloads/iars/my-great-items.iar
will load my-great-items.iar from the web into Folder2 of the user "Bertrand Russell".
Upcoming functionality
In Git master code, there is now a --merge option in the "load iar" command
load iar [--merge] <user name> <path> <password> [<filename>]
If the --merge option is given, then IAR items are loaded into the existing folder structure where possible, instead of always creating new folders.
This feature will debut in OpenSim 0.7.1.
Examples
Let's suppose that a user called Albert Camus has an existing inventory structure
My Inventory
|
+-- FolderA
| |
| +-- Item1
|
+-- FolderC
|
+-- Item2
and we execute
load iar --merge Albert Camus / PASSWORD my-items.iar
with the IAR saved above. Instead of creating a duplicate FolderA, this will instead result in the inventory structure
My Inventory
|
+-- FolderA
| |
| +-- FolderB
| | |
| | +-- ItemX
| |
| +-- Item1
| |
| +-- ItemY
|
+-- FolderC
|
+-- Item2
The --merge option is useful if you are restoring a saved inventory to a new user account, since the base folders (Gestures, Landmarks, Objects, etc.) will not be duplicated.
IAR files
http://justincc.org/downloads/iars/my-great-items.iar - justincc's initial example IAR.
[1] - Gene Jacobs Men's Clothing Collection (Original Creator)
[2] - Female Skins and Shapes (Found off the web)
Please feel free to place links to other IARs here.
Further Information
http://justincc.org/blog/category/iars/ - articles by justincc on IARs, including tutorials, background information and possible future developments.
The OpenSim Library just got more interesting - Diva Canto's article on how to extend the OpenSim Library using IARs.
Use cases
Possible uses
1. To distribute content to other OpenSim installations without need to transfer entire regions. One drawback with IARs for this use case is that creator names are not preserved unless the user has a profile on the target installation. One workaround is to include a notecard detailing the creator and license conditions of the content.
2. To backup a user's inventory. IARs are currently not that great for this. One can backup an entire inventory by giving a path of "/" to the save iar command. But a load IAR of the same will mean a duplicate set of root child 'standard' folders (Objects, Textures, Clothing, etc.). The loaded folders will not have any type icons.
Current limitations
- IAR loading and saving is currently done on a single thread. This may lock up the console for a while with very large IARs. This should be addressed in the future
- Creator names are not preserved unless the profile exists on the target system. This problem may be addressed in the future.
File Formats
FAQ
Nothing yet.
Bugs
Please search the OpenSim Mantis for information on current IAR bugs.
FEB.23.2010:
There is a slight "quirk" with MySql in regards to Max_Allowed_Packet size, which the default is 1 Megabyte. This is too small for some of the larger data blobs being stored. It is recomended to increase the default value to 16 Megabytes.
Locate your MY.ini for MySql (EXAMPLE, in Windows it is located @ "C:\Program Files\MySQL\MySQL Server 5.1") Modify this file to include the following under the mysqld section:
[mysqld]
- The TCP/IP Port the MySQL Server will listen on
port=3306
max_allowed_packet = 16M
Additional Reference: dev.mysql.com/doc/refman/5.1/en/packet-too-large.html
Current Status
Operational but experimental. Bug reports are appreciated and there will almost certainly be quite a few right now. Suggestions for improvement are also welcome. The best place for these right now might be my blog post on IARs, since I'm bound to see them then.
Though we will strive to maintain compatibilty for old archives with newer OpenSimulator versions, please do not rely on these archives as your only backup for inventory.
