OpenSim Archives

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
m (remove dead links, not found in the wayback machine.)
 
(27 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{Quicklinks}}
 
{{Quicklinks}}
  
=How do I use the OpenSim Archive Function?=
+
= Introduction =
  
==Introduction==
+
The OpenSimulator Archive (OAR) function has existed since OpenSimulator 0.5.9. The facility does a similar job to load-xml2/save-xml2 in that it saves prims so that they can be later reloaded. However, OpenSimulator archives (OAR) go a step further in that they can save all the necessary asset data so that you may fully restore the terrain, region parcel data, the textures of objects and their inventories when loaded onto a completely different system using a different asset database.
  
The OpenSim Archive (OAR) function has existed since OpenSim 0.5.9.  The facility does a similar job to load-xml2/save-xml2 in that it saves prims so that they can be later reloaded.  However, OpenSim archives (OAR) go a step further in that they can save all the necessary asset data so that you may fully restore the terrain, region parcel data, the textures of objects and their inventories when loaded onto a completely different system using a different asset database.
+
= Usage =
 
+
== Usage ==
+
  
 
From the region console, one can type  
 
From the region console, one can type  
  
  save oar [--noassets] [-h|--home=<url>] [<filename>]
+
  save oar [--noassets] [-h|--home=<url>] [--publish] [--perm=<permissions>] [--all] [<filename>]
  
to save an OpenSim archive. If no filename is given, then the name region.oar is used in the current directory.
+
to save an OpenSimulator archive. If no filename is given, then the name region.oar is used in the current directory.  
  
 
'''EXAMPLES:'''
 
'''EXAMPLES:'''
Line 23: Line 21:
 
To load an archive, type  
 
To load an archive, type  
  
  load oar [--merge] [<location>]
+
  load oar [options] [<path-to-oar>]
  
at the console. The location can be a filesystem path (as for "save oar") or an HTTP address to load an oar directly over the web. If no location is given, then the server looks for a file called region.oar in the current directory.  
+
at the console. The location can be a filesystem path (as for "save oar") or an HTTP address to load an oar directly over the web. If no location is given, then the server looks for a file called region.oar in the current directory. See detailed "load oar" documentation at [[Load Oar]].
  
 
'''EXAMPLES:'''
 
'''EXAMPLES:'''
 
  load oar
 
  load oar
 +
load oar my.oar
 
  load oar my.oar
 
  load oar my.oar
 
  load oar --merge oars/3rd-party.oar
 
  load oar --merge oars/3rd-party.oar
Line 35: Line 34:
 
By default, loading an archive will delete all the existing objects in the regions and replace them with the archive contents. It's like being in the Matrix (when they swap environments), except much slower (all the scene objects are slowly deleted before the new environment is loaded :-)  
 
By default, loading an archive will delete all the existing objects in the regions and replace them with the archive contents. It's like being in the Matrix (when they swap environments), except much slower (all the scene objects are slowly deleted before the new environment is loaded :-)  
  
When an archive is loaded, owners will be restored if the relevant uuids can be found in the OpenSim installation's user database. Otherwise, prim ownership will default to the master avatar for the region.  
+
When an archive is loaded, owners will be restored if the relevant uuids can be found in the OpenSimulator installation's user database. Otherwise, prim ownership will default to the master avatar for the region.  
  
 
I recommend that you use filenames with the extension '''.oar'''. The filename extension of the download links on this page is '''.tar.gz''' which illustrates that the '''.oar''' format is actually a zipped tar file.
 
I recommend that you use filenames with the extension '''.oar'''. The filename extension of the download links on this page is '''.tar.gz''' which illustrates that the '''.oar''' format is actually a zipped tar file.
  
=== Switches ===
+
== Switches ==
==== Saving ====
+
=== Saving ===
  
===== --noassets =====
+
==== --publish ====
  
If the --noassets option is specified then the oar will be saved without assets.  This can be handy if you're backing up the asset database separately and don't want the expense of including all the assets in each OAR.
+
If set, then objects in the saved oar are stripped of owner and last owner information, though not of creator information.
  
===== --home =====
+
This is useful if you are publishing OARs (rather than using them for backup) where those OARs might be loaded to the same grid from which you published.
 +
 
 +
As of OpenSimulator 0.7.4, this switch will also strip ownership information from land parcels.
 +
 
 +
As of OpenSimulator 0.8.0, this switch will also strip group information from the OAR.
 +
 
 +
==== --noassets ====
 +
 
 +
If the --noassets option is specified then the oar will be saved without assets. This can be handy if you're backing up the asset database separately and don't want the expense of including all the assets in each OAR.
 +
 
 +
==== --home ====
  
 
(formerly known as --profile up to 0.7.3)
 
(formerly known as --profile up to 0.7.3)
Line 57: Line 66:
 
   save oar --home=http://mygrid.com my.oar
 
   save oar --home=http://mygrid.com my.oar
  
==== Loading ====
+
==== --perm ====
 +
 
 +
If the --perm option is specified then objects with insufficient permissions will not be saved to the OAR. The user whose permissions are checked is the estate owner. This can be useful for grids that allow their customers to export their regions to OARs, because it ensures that exporting to OAR can't be used to bypass content permissions.
 +
 
 +
<permissions> specifies which permissions are required. It's a string that contains one or more of these characters:
 +
* "C" = Copy
 +
* "T" = Transfer
 +
 
 +
Example:
 +
  save oar --perm=CT my.oar
 +
 
 +
==== --all ====
 +
 
 +
If the --all option is specified then the OAR will contain all the regions in the simulator. If this option isn't specified (which is the default) then the OAR will contain only the current region.
 +
 
 +
=== Loading ===
 +
This is an overview of the most common parameters. There are many more documented at [[Load Oar]].
 +
 
 +
==== --skip-assets ====
 +
 
 +
If set, this will not attempt to load any of the assets from the OAR, though all other data will be loaded.  This can be useful if you are loading the OAR back into a grid that you know already contains the assets.
  
===== --merge =====
+
==== --merge ====
  
 
If the --merge option is specified then the oar will be merged with the existing region objects rather than replace them. The existing terrain, region settings and parcels will be left in place.
 
If the --merge option is specified then the oar will be merged with the existing region objects rather than replace them. The existing terrain, region settings and parcels will be left in place.
  
==Example OARs==
+
= Multi-Region OARs =
  
[http://www.secondlifelab.it/downloads/cyberlandia.tar.gz cyberlandia.tar.gz] - cyberlandia landscape designed by the architect Simone Riccardi aka turboy. Contemporary architecture surrounded with a natural/synthetic context [http://www.flickr.com/photos/8905571@N05/3182585775/ image_1] [http://www.flickr.com/photos/8905571@N05/3171070049/ image_2] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]).
+
By default, the save-oar command saves only the current region into the OAR (using OAR Format 0.8). However, if the --all option is specified then all the regions in the simulator are saved into a multi-region OAR file (using OAR Format 1.0). This is useful when saving a build that spans multiple regions.
  
 +
The load-oar command supports both OAR formats (0.x and 1.x). When it's given a 1.x OAR file it loads all the regions in the OAR into the corresponding regions in the simulator, according to their position relative to the root region. If the simulator doesn't have a region in a location that is present in the OAR then that region isn't loaded.
  
===OpenVCE 3D Assets OAR===
+
For historical context, see [[Feature_Proposals/Multi-Region_OARs]] and [http://opensimulator.org/mantis/view.php?id=6105 Mantis 6105]
 +
 
 +
= Example OARs =
 +
 
 +
== OpenVCE 3D Assets OAR ==
  
 
The [http://openvce.net OpenVCE.net] virtual worlds assets described at http://openvce.net/vwassets provided by Clever Zebra and the OpenVCE.net team at AIAI in the University of Edinburgh are available as an OAR (Opensim Archive) file.
 
The [http://openvce.net OpenVCE.net] virtual worlds assets described at http://openvce.net/vwassets provided by Clever Zebra and the OpenVCE.net team at AIAI in the University of Edinburgh are available as an OAR (Opensim Archive) file.
Line 78: Line 112:
 
[http://openvce.net/resources/downloads/opensim-openvce-2.jpg Image 2]
 
[http://openvce.net/resources/downloads/opensim-openvce-2.jpg Image 2]
  
=== Others ===
+
== Others ==
  
 
Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.  
 
Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.  
  
[http://www.opensimworlds.com/index.php?part=worlds http://www.opensimworlds.com/index.php?part=worlds]
+
[http://www.hypergridbusiness.com/2011/06/where-to-get-content-for-opensim/ Where to get content for OpenSim]&nbsp;-- Hypergrid Business page, regularly updated, containing links to major OAR sites. Also has download links to individual OAR files.  
  
[http://www.rexxed.com/category/sim/ http://www.rexxed.com/category/sim/]<br>
+
[http://www.zadaroo.com/ Zadaroo.com]
 +
 
 +
[http://www.outworldz.com/cgi/freesculpts.plx?q=OAR- Outworldz.com]  
  
 
[http://forums.osgrid.org/viewforum.php?f=20 http://forums.osgrid.org/viewforum.php]
 
[http://forums.osgrid.org/viewforum.php?f=20 http://forums.osgrid.org/viewforum.php]
  
==Further Information==
+
= Tools =
 +
 
 +
* [https://github.com/justincc/opensimulator-tools/tree/master/analysis/oarinfo] - oarinfo.py, a very basic Python script for printing out information about an OAR (number of contained objects, assets, etc.).
 +
 
 +
= Further Information =
  
 
* [http://justincc.org/blog/category/oars/ http://justincc.org/blog/category/oars/] - various OAR related articles from justincc, including background information and possible future development.
 
* [http://justincc.org/blog/category/oars/ http://justincc.org/blog/category/oars/] - various OAR related articles from justincc, including background information and possible future development.
  
==Use cases==
+
= Use cases =
  
 
Possible current uses are
 
Possible current uses are
  
1. To migrate data from an SQLite region database to one based on MySQL
+
1. To migrate data from an SQLite region database to one based on MySQL
  
2. To distribute entire regions to other people.
+
2. To distribute entire regions to other people.
  
==Current limitations==
+
= Current limitations =
  
* Performance is not very good, especially with large archives. This will be addressed in the future
+
* Performance is not very good with large archives. This will be addressed in the future
* Loading large OARs using the default SQLite database plugin will take a very very long time (in the order of many hours). I highly recommend that you switch to MySQL if you want to load large archives.
+
* Loading large OARs using the default SQLite database plugin will take a very very long time (in the order of many hours). I highly recommend that you switch to MySQL if you want to load large archives.
  
==Upcoming enhancements==
+
= OAR Format =
  
===== --perm =====
+
The region [[OpenSim Archives|OpenSimulator Archive (OAR)]] format is designed with three aims in mind:
 
+
A new option will be added when saving OARs:
+
 
+
save oar [--perm=&lt;permissions&gt;]
+
 
+
If the --perm option is specified then objects with insufficient permissions will not be saved to the OAR. The user whose permissions are checked is the estate owner. This can be useful for grids that allow their customers to export their regions to OARs, because it ensures that exporting to OAR can't be used to bypass content permissions.
+
 
+
<permissions> specifies which permissions are required. It's a string that contains one or more of these characters:
+
* "C" = Copy
+
* "T" = Transfer
+
 
+
Example:
+
  save oar --perm=CT my.oar
+
 
+
==OAR Format==
+
 
+
The region [[OpenSim_Archives|OpenSim Archive (OAR)]] format is designed with three aims in mind:
+
  
 
# Make it easy for people to read and change individual objects, assets, etc. within an archive.
 
# Make it easy for people to read and change individual objects, assets, etc. within an archive.
Line 132: Line 155:
 
Therefore, all the different entities (assets, objects, terrains, etc.) are packaged in individual files (e.g. one for each asset) with human readable filenames and machine readable extensions (e.g. .jp2 for textures, .txt for notecards).
 
Therefore, all the different entities (assets, objects, terrains, etc.) are packaged in individual files (e.g. one for each asset) with human readable filenames and machine readable extensions (e.g. .jp2 for textures, .txt for notecards).
  
*[[OAR Format 0.1]]
+
* [[OAR Format 0.1]]
*[[OAR Format 0.2]]
+
* [[OAR Format 0.2]]
*[[OAR Format 0.6]]
+
* [[OAR Format 0.6]]
*[[OAR Format 0.7]]
+
* [[OAR Format 0.7]]
 +
* [[OAR Format 0.8]] - the current default OAR save format.
 +
* [[OAR Format 1.0]]
  
==FAQ==
+
== OAR Format Compatibility ==
  
1. What is this .tar.gz format you are using for the internal OAR format?  Why not zip?
+
All version 0.x OARs can be read by any earlier version of OpenSimulator, even if some of the content is ignored.
  
.tar.gz is a standard unix way of zipping up files into a single larger compressed file for distribution.  Windows users should be able to open these files using freeware programs such as [http://www.7-zip.org/ 7-zip].
+
OAR Format 1.0 isn't backwards-compatible, so it can only be read in OpenSim 0.7.5 and above. However, since most current instances of OpenSim can't read this format, there is a transition period in which OpenSim still saves single-region OARs using OAR Format 0.8. This means that the most common behavior (save-oar for a single region) creates OARs that are readable by all instances of OpenSim. The new OAR Format 1.0 is only used when using the --all option.
  
I'm using .tar.gz because all the zip (and tar) libraries for .net are licensed either under the GPL (with exception) or under the MSPL.  Unfortunately, not all members of the OpenSim development team are comfortable with the MSPL, so these libaries are not currently an option.  It is also significantly easier to write code to create and read tar archives than zip archives.
+
= FAQ =
  
Also, if you're only ever loading and saving oars (rather than pulling them apart and putting them back together), then you don't need to worry about the internal format at all :)
+
1. What is this .tar.gz format you are using for the internal OAR format? Why not zip?
  
 +
.tar.gz is a standard unix way of zipping up files into a single larger compressed file for distribution. Windows users should be able to open these files using freeware programs such as [http://www.7-zip.org/ 7-zip].
  
2. Can you load and save multiple regions to an archive?
+
I'm using .tar.gz because all the zip (and tar) libraries for .net are licensed either under the GPL (with exception) or under the MSPL. Unfortunately, not all members of the OpenSimulator development team are comfortable with the MSPL, so these libaries are not currently an option. It is also significantly easier to write code to create and read tar archives than zip archives.
  
Not yet.
+
Also, if you're only ever loading and saving oars (rather than pulling them apart and putting them back together), then you don't need to worry about the internal format at all :)
  
 +
2. Can you load and save multiple regions to an archive?
  
3. Can you load and save parts of a region to an archive?
+
Yes, since OpenSim 0.7.5. See [[OpenSim Archives#Multi-Region OARs]]
 +
 
 +
3. Can you load and save parts of a region to an archive?
  
 
Not yet.
 
Not yet.
  
==Bugs==
+
= Current Status =
  
* Due to a possible bug in the Mono 1.2.4 libraries, this feature may cause a debug dump when used (the problem appears to be in writing out a compressed stream).  Mono 1.2.6 is okay.  Since Mono 1.2.4 is fairly old now, this bug will not be addressed.
+
Operational. Bug reports are appreciated [[User:Justincc|Justincc]] 14:53, 14 September 2009 (UTC)
 
+
==Current Status==
+
 
+
Operational. Bug reports are appreciated [[User:Justincc|Justincc]] 14:53, 14 September 2009 (UTC)
+
  
 
Though we will strive to maintain compatibilty for old archives with newer OpenSimulator versions, please don't rely on these archives as the only backup for regions.
 
Though we will strive to maintain compatibilty for old archives with newer OpenSimulator versions, please don't rely on these archives as the only backup for regions.
  
 
+
[[Category:Users]]
[[Category:Users]] [[Category:Support]] [[Category:Tech_Reference]] [[Category:Help]] [[Category:Configuration]] [[Category:Getting_Started]] [[Category:Development]]
+
[[Category:Support]]
 +
[[Category:Tech Reference]]
 +
[[Category:Help]]
 +
[[Category:Configuration]]
 +
[[Category:Getting Started]]
 +
[[Category:Development]]

Latest revision as of 17:31, 26 November 2016

Contents

[edit] Introduction

The OpenSimulator Archive (OAR) function has existed since OpenSimulator 0.5.9. The facility does a similar job to load-xml2/save-xml2 in that it saves prims so that they can be later reloaded. However, OpenSimulator archives (OAR) go a step further in that they can save all the necessary asset data so that you may fully restore the terrain, region parcel data, the textures of objects and their inventories when loaded onto a completely different system using a different asset database.

[edit] Usage

From the region console, one can type

save oar [--noassets] [-h|--home=<url>] [--publish] [--perm=<permissions>] [--all] [<filename>]

to save an OpenSimulator archive. If no filename is given, then the name region.oar is used in the current directory.

EXAMPLES:

save oar
save oar my.oar
save oar c:/mybackups/filename.oar
save oar oars/11nov.oar

To load an archive, type

load oar [options] [<path-to-oar>]

at the console. The location can be a filesystem path (as for "save oar") or an HTTP address to load an oar directly over the web. If no location is given, then the server looks for a file called region.oar in the current directory. See detailed "load oar" documentation at Load Oar.

EXAMPLES:

load oar
load oar my.oar
load oar my.oar
load oar --merge oars/3rd-party.oar
load oar http://path.to/oarfile.oar

By default, loading an archive will delete all the existing objects in the regions and replace them with the archive contents. It's like being in the Matrix (when they swap environments), except much slower (all the scene objects are slowly deleted before the new environment is loaded :-)

When an archive is loaded, owners will be restored if the relevant uuids can be found in the OpenSimulator installation's user database. Otherwise, prim ownership will default to the master avatar for the region.

I recommend that you use filenames with the extension .oar. The filename extension of the download links on this page is .tar.gz which illustrates that the .oar format is actually a zipped tar file.

[edit] Switches

[edit] Saving

[edit] --publish

If set, then objects in the saved oar are stripped of owner and last owner information, though not of creator information.

This is useful if you are publishing OARs (rather than using them for backup) where those OARs might be loaded to the same grid from which you published.

As of OpenSimulator 0.7.4, this switch will also strip ownership information from land parcels.

As of OpenSimulator 0.8.0, this switch will also strip group information from the OAR.

[edit] --noassets

If the --noassets option is specified then the oar will be saved without assets. This can be handy if you're backing up the asset database separately and don't want the expense of including all the assets in each OAR.

[edit] --home

(formerly known as --profile up to 0.7.3)

If the --home option is specified then all names of creators from this world will be appended with links to their home world. It is not required that the service be operational; the information will be added and it will be available in all worlds that import this OAR.

<url> is the URL of this world's profile service.

Example:

 save oar --home=http://mygrid.com my.oar

[edit] --perm

If the --perm option is specified then objects with insufficient permissions will not be saved to the OAR. The user whose permissions are checked is the estate owner. This can be useful for grids that allow their customers to export their regions to OARs, because it ensures that exporting to OAR can't be used to bypass content permissions.

<permissions> specifies which permissions are required. It's a string that contains one or more of these characters:

  • "C" = Copy
  • "T" = Transfer

Example:

 save oar --perm=CT my.oar

[edit] --all

If the --all option is specified then the OAR will contain all the regions in the simulator. If this option isn't specified (which is the default) then the OAR will contain only the current region.

[edit] Loading

This is an overview of the most common parameters. There are many more documented at Load Oar.

[edit] --skip-assets

If set, this will not attempt to load any of the assets from the OAR, though all other data will be loaded. This can be useful if you are loading the OAR back into a grid that you know already contains the assets.

[edit] --merge

If the --merge option is specified then the oar will be merged with the existing region objects rather than replace them. The existing terrain, region settings and parcels will be left in place.

[edit] Multi-Region OARs

By default, the save-oar command saves only the current region into the OAR (using OAR Format 0.8). However, if the --all option is specified then all the regions in the simulator are saved into a multi-region OAR file (using OAR Format 1.0). This is useful when saving a build that spans multiple regions.

The load-oar command supports both OAR formats (0.x and 1.x). When it's given a 1.x OAR file it loads all the regions in the OAR into the corresponding regions in the simulator, according to their position relative to the root region. If the simulator doesn't have a region in a location that is present in the OAR then that region isn't loaded.

For historical context, see Feature_Proposals/Multi-Region_OARs and Mantis 6105

[edit] Example OARs

[edit] OpenVCE 3D Assets OAR

The OpenVCE.net virtual worlds assets described at http://openvce.net/vwassets provided by Clever Zebra and the OpenVCE.net team at AIAI in the University of Edinburgh are available as an OAR (Opensim Archive) file.

http://openvce.net/resources/downloads/

Get file "opensim-openvce.oar" from there (right click on the file in the above directory in your browser, and select download is the easiest way to obtain the materials). A "full" set of the buildings with a large 400 seat amphitheatre intended to be placed on the corner of 4 sims is also available via "opensim-openvce-full.oar". Images of the buildings in place in Opensim are at: Image 1, Image 2

[edit] Others

Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.

Where to get content for OpenSim -- Hypergrid Business page, regularly updated, containing links to major OAR sites. Also has download links to individual OAR files.

Zadaroo.com

Outworldz.com

http://forums.osgrid.org/viewforum.php

[edit] Tools

  • [1] - oarinfo.py, a very basic Python script for printing out information about an OAR (number of contained objects, assets, etc.).

[edit] Further Information

[edit] Use cases

Possible current uses are

1. To migrate data from an SQLite region database to one based on MySQL

2. To distribute entire regions to other people.

[edit] Current limitations

  • Performance is not very good with large archives. This will be addressed in the future
  • Loading large OARs using the default SQLite database plugin will take a very very long time (in the order of many hours). I highly recommend that you switch to MySQL if you want to load large archives.

[edit] OAR Format

The region OpenSimulator Archive (OAR) format is designed with three aims in mind:

  1. Make it easy for people to read and change individual objects, assets, etc. within an archive.
  2. Make it easy to compose two region archives into a single region archive.
  3. Make it easy to compose archives from scratch.

Therefore, all the different entities (assets, objects, terrains, etc.) are packaged in individual files (e.g. one for each asset) with human readable filenames and machine readable extensions (e.g. .jp2 for textures, .txt for notecards).

[edit] OAR Format Compatibility

All version 0.x OARs can be read by any earlier version of OpenSimulator, even if some of the content is ignored.

OAR Format 1.0 isn't backwards-compatible, so it can only be read in OpenSim 0.7.5 and above. However, since most current instances of OpenSim can't read this format, there is a transition period in which OpenSim still saves single-region OARs using OAR Format 0.8. This means that the most common behavior (save-oar for a single region) creates OARs that are readable by all instances of OpenSim. The new OAR Format 1.0 is only used when using the --all option.

[edit] FAQ

1. What is this .tar.gz format you are using for the internal OAR format? Why not zip?

.tar.gz is a standard unix way of zipping up files into a single larger compressed file for distribution. Windows users should be able to open these files using freeware programs such as 7-zip.

I'm using .tar.gz because all the zip (and tar) libraries for .net are licensed either under the GPL (with exception) or under the MSPL. Unfortunately, not all members of the OpenSimulator development team are comfortable with the MSPL, so these libaries are not currently an option. It is also significantly easier to write code to create and read tar archives than zip archives.

Also, if you're only ever loading and saving oars (rather than pulling them apart and putting them back together), then you don't need to worry about the internal format at all :)

2. Can you load and save multiple regions to an archive?

Yes, since OpenSim 0.7.5. See OpenSim Archives#Multi-Region OARs

3. Can you load and save parts of a region to an archive?

Not yet.

[edit] Current Status

Operational. Bug reports are appreciated Justincc 14:53, 14 September 2009 (UTC)

Though we will strive to maintain compatibilty for old archives with newer OpenSimulator versions, please don't rely on these archives as the only backup for regions.

Personal tools
General
About This Wiki