Installing and Running Hypergrid
From OpenSimulator
Installing & Running OpenSim in Hypergrid Mode
Revised Jan.07,2010. Effective from OpenSim 0.6.7 Post Fixes to 0.6.9 <dev> GIT# a542871 - r11916
Subject to change in future
Installing
Checkout OpenSim, prebuild and build as normal or Download and install Binary Packages from the MAIN Page
If you're running your opensim in Grid Mode mode with servers on other machines, you only need to modify your OpenSim.ini to enable HyperGrid.
If you're running in standalone and you want it to be network-able, or if you have your grid on loopback (127.0.0.1) change all the [Network] server addresses to. See below.
EXAMPLE Network Sections
Default Example, Network Settings for a Stand Alone:
[Network] http_listener_port = 9000 grid_server_url = "http://example.com:9000" grid_send_key = null grid_recv_key = null user_server_url = "http://example.com:9000" user_send_key = null user_recv_key = null asset_server_url = "http://example.com:9000" inventory_server_url = "http://example.com:9000" messaging_server_url = "http://example.com:9000"
Default Example, Network Settings for a Grided Server:
[Network] http_listener_port = 9000 grid_server_url = "http://example.com:8001" grid_send_key = null grid_recv_key = null user_server_url = "http://example.com:8002" user_send_key = null user_recv_key = null asset_server_url = "http://example.com:8003" inventory_server_url = "http://example.com:8003" messaging_server_url = "http://example.com:8006"
Network Settings for OSGrid Attched Servers:
[Network] http_listener_port = 9000 grid_server_url = "http://osgrid.org:8001" ;default 8003 grid_send_key = "1234" grid_recv_key = "1234" user_server_url = "http://osgrid.org:8002" user_send_key = "1234" user_recv_key = "1234" asset_server_url = "http://assets.osgrid.org:8003" inventory_server_url = "http://osgrid.org:8004" ;default 8003 messaging_server_url = "http://osgrid.org:8006"
Modifications needed to be applied to OpenSim.ini to enable Hypergrid
- Change the following line at the top of the OpenSim.ini
hypergrid = false to true
- NEXT, Add or Modify the ### WORLD MAP Section as shown
; ## ; ## WORLD MAP ; ## WorldMapModule = "WorldMap" MapImageModule = "MapImageModule" WorldMapModule = "HGWorldMapModule" ;NOT INCLUDED IN DEFAULT OpenSim.ini.EXAMPLE
Information: HGWorldMapModule will, after teleporting to another grid, clean up tiles in your map left over from the grid on which you were previously.
- NEXT, Modify the [Archictecture] Section at the bottom
Uncomment the appropriate Include-HG* = line by removing the semi colon and making sure that is the only ONE uncommented. (example shows for a Stand Alone HG enabled installation)
[Architecture] ;Include-Standalone = "config-include/Standalone.ini" ; DEFAULT UNCOMMENTED Include-HGStandalone = "config-include/StandaloneHypergrid.ini" ;Include-Grid = "config-include/Grid.ini" ;Include-HGGrid = "config-include/GridHypergrid.ini"
Your OpenSimulator instance should now be ready for inbound & outbound Hypergrid use
Limitations:
Due to a viewer issue, you cannot teleport more than 4096 regions away. Some 3rd party Viewers have addressed this limitation. What this means, is that if you wish to teleport from a region located at 1000,1000 XY coordinates you cannot go beyond 5095. For Instance OSGrid is centered @ 10,000x10,000
Refer to Public Hypergrid Nodes to see some known grids / StandAlones and others and where they are located.
Important Notes:
Make sure you have a 'home' set. If your home region doesn't exist, the hyperlink TPs may not work. To set your home, go to one of your local regions and "Set Home" from the viewer.
To Enable scripted Teleporting between regions, standalone, HyperGrid etc, you can use osTeleprotAgent function, Example here: OsTeleportAgent
Linking regions (Optional)
Method 1
On the console, type for example:
link-region <Xloc> <Yloc> osl2.nac.uci.edu:9006
Use Xloc and Yloc that make sense to your world, i.e. close to your regions, but not adjacent.
replace osl2.nac.uci.edu and 9006 with the domain name / ip address and the http_listener_port of the simulator where the region is running you want to link to.
You can link to a specific region within an instance, by using the name of the region at the end, for example:
link-region 997 997 osl2.nac.uci.edu:9006:UCI Welcome
Method 2
There is also some initial support for reading the links from a xml file.
Use the console command: link-region <URI> [<excludeList>]
The uri can be either the path of a local xml file or a xml document on a http server.
The format of the xml file is:
<Nini> <Section Name="Region1"> <Key Name="xloc" Value="1002"/> <Key Name="yloc" Value="1006" /> <Key Name="externalPort" Value="9006" /> <Key Name="externalHostName" Value="osl2.nac.uci.edu" /> <Key Name="localName" Value="OSGrid-Gateway" /> <Key Name="real-xloc" Value="10222"/> //optional field that gives the region's real location on its home grid <Key Name="real-yloc" Value="10265" /> //optional field that gives the region's real location on its home grid </Section> <Section Name="Region2"> ... </Section> ... </Nini>
[Note] The section names can be anything you want, but they all should be different and have no spaces in the name.
ExcludeList:
The exclude list is a single string paramater with the format: excludeList:<SectionName>[;<SectionName>]
This means that while reading from the xml file any sections that are listed in the excludeList will be ignored and no HyperGrid link created for them.
This could allow, link lists to be created on a webserver that everyone could add their own regions to, and then they just make sure they add their own section name(s) to the exclude list on their own region(s).
So for example, someone might create a editable online list for the up coming OpenSimulator's 2nd birthday. Which might look something like:
<Nini> <Section Name="OSGrid-Party"> <Key Name="xloc" Value="1002"/> <Key Name="yloc" Value="1006" /> <Key Name="externalPort" Value="9006" /> <Key Name="externalHostName" Value="osl2.nac.uci.edu" /> <Key Name="localName" Value="OSGrid-Gateway" /> </Section> <Section Name="UCIGrid-Party"> ... </Section> </Nini>
"link-region <URI of xml file> excludeList:MW-Party"
This is so that my region doesn't try to create a hyper link to itself.
Method 3 (dynamic)
Starting in r8193, if you're in an HG-enabled region, you'll be able to dynamically link sims, and TP there, in any one of these ways (and probably more). All you need to know is the target address, e.g. from the list below.
1) Type for example secondlife://ucigrid04.nacs.uci.edu:9007/ in the chat box, pull up the chat history and click on that link
2) Pull up the map and search for things like ucigrid04.nacs.uci.edu:9007
3) Using the embedded browser visit pages that have links like secondlife://ucigrid04.nacs.uci.edu:9007/ (there's one up at http://www.ics.uci.edu/~lopes/hypergrid/test.html)
Again, you can link to a specific region within an instance by adding the name of that region at the end, like this: secondlife://ucigrid04.nacs.uci.edu:9007:Gateway 7000/
Important Notes
- Due to a viewer bug, you can only TP between regions that are no more than 4096 cells apart in any dimension. What this means in practice is that if you want to link to OSGrid, you must have your own regions reachable from the (10,000; 10,000) point on the map, which is where OSGrid is centered. Place your regions somewhere in the 8,000s or the 12,000s.
- With grid mode, methods 1 and 2 will work on both the Robust console and the region console. On the region console, linked regions will not be stored in the database and will vanish when the region is shut down. Regions that are linked on the Robust console will be persistent over restarts until they are explicitly removed with unlink-region.
Listing linked regions
To see a list of all linked regions, use the following command on the console (available since 0.7.1 r/13457, also in 0.7-post-fixes):
show hyperlinks
Unlinking regions
On the console, type for example:
unlink-region osl2.nac.uci.edu:9006
or
unlink-region <local region name>
Please note that region names can only have a maximum length of 32 characters when using MySQL as a database. If a linked region has a longer name, it will be truncated. The unlink-region command will only find a region, if the name is also truncated to a maximum length of 32 characters.
Additional References
Implemented osFunctions: OSSL Implemented
Enabling osFunctions: OSSL Enabling Functions
HyperGrid Security: Hypergrid Security
Banning Foreign Users in Hypergrid: Banning Foreign Users in Hypergrid
Public HyperGrid Nodes Listing: Public Hypergrid Nodes
Hypergrid Inventory Access: Hypergrid Inventory Access (proposal)
CATEGORY: Hypergrid
