Installing and Running Hypergrid
From OpenSimulator
Contents |
Installing & Running OpenSim in Hypergrid Mode
The setup for hypergrid differs depending on whether you run OpenSim as a standalone or as a grid. There also came considerable changes with version 0.7. If you are using an older version 0.6.x of OpenSimulator, then refer to #Configuration for OpenSimulator 0.6.x further down this page.
Configuration
In order for OpenSimulator to be accessible in the hypergrid, you must use an externally visible IP address or domain name. You also may need to set up port forwarding for all ports (TCP and UDP) that OpenSimulator and the regions use. Typically, these are port 8002 for an installation running in grid mode and port 9000 for standalones. Regions typically use ports starting at 9000. For more information, see Network Settings.
Standalone
The configuration for hypergrid is activated in section [Architecture] in file OpenSim.ini. Ensure that the line for Include-HGStandalone is the only one that is uncommented in this section:
[Architecture] ;Include-Standalone = "config-include/Standalone.ini" Include-HGStandalone = "config-include/StandaloneHypergrid.ini" ;Include-Grid = "config-include/Grid.ini" ;Include-HGGrid = "config-include/GridHypergrid.ini" ;Include-SimianGrid = "config-include/SimianGrid.ini"
In StandaloneCommon.ini the network addresses in sections [LoginService] and [GatekeeperService] must be changed to your external network address:
[LoginService] ; ... (other settings in this section) ... HomeURI = "http://example.com:9000" GatekeeperURI = "http://example.com:9000" InventoryServerURI = "http://example.com:9000" AssetServerURI = "http://example.com:9000" [GatekeeperService] ; ... (other settings in this section) ... ExternalName = "http://example.com:9000"
If you want to use a different port with these addresses, then you must adjust the HTTP listener port in section [Network] in OpenSim.ini, too:
[Network] ; ... (other settings in this section) ... http_listener_port = 9000
As a last step, the regions must be configured according to the previous changes. See #Region Setup for both Grid and Standalone.
Grid
To enable hypergrid for a grid, both the Robust server and the region servers (simulators) must be configured approprietly.
Robust Server
The Robust server is started with configuration file Robust.HG.ini instead of Robust.ini. If this file does not yet exist in your installation, create it by making a copy of Robust.HG.ini.example. Make the changes appropriate for your environment (e.g. adjust the database connection string). For hypergrid, the following settings are relevant:
[LoginService] ; ... (other settings in this section) ... HomeURI = "http://example.com:8002" GatekeeperURI = "http://example.com:8002" InventoryServerURI = "http://example.com:8002" AssetServerURI = "http://example.com:8002" [GatekeeperService] ; ... (other settings in this section) ... ExternalName = "http://example.com:8002"
If you want to change the port(s) used with these addresses, you will also need to adjust the ports in parameter 'ServiceConnectors' in section [Startup] and probably the port configured in section [Network] as well.
After these adjustments, the Robust server can be started. On Windows/.NET:
Robust -inifile=Robust.HG.ini
Or, with Mono (e.g. on Linux or OSX):
mono Robust.exe -inifile=Robust.HG.ini
Simulator
The region servers (simulators) that connect to the Robust server read their configuration from file OpenSim.ini. To activate hypergrid for them, the line for Include-HGGrid in section [Architecture] must be uncommented:
[Architecture] ;Include-Standalone = "config-include/Standalone.ini" ;Include-HGStandalone = "config-include/StandaloneHypergrid.ini" ;Include-Grid = "config-include/Grid.ini" Include-HGGrid = "config-include/GridHypergrid.ini" ;Include-SimianGrid = "config-include/SimianGrid.ini"
Region Setup for both Grid and Standalone
Finally, all your regions must use the same external address that is set for GatekeeperService, for example:
[Region One] ; ... (other settings in this section) ... ExternalHostName = "example.com"
For the ports which are used by your regions, TCP and UDP requests must be forwarded through any firewall that is securing your network.
Configuration for OpenSimulator 0.6.x
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
The 4096 Regions Limit
Due to a viewer issue, teleports to destinations that are more than 4096 regions away in any direction will not work as expected. Most viewers will do the teleport but the destination region will not be rendered and thus remain invisible to you. What this means in practice is that if you wish to teleport from a region located at cell coordinates (1000, 1000) you cannot go beyond (5095, 5095). To reach destinations that are placed at farer locations, you should either place your own region closer to the destination, or use some intermediate region that is reachable from both your region and the destination region.
Refer to Public Hypergrid Nodes to see some known grids and standalones 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 osTeleportAgent function, Example here: OsTeleportAgent
Linking regions (Optional)
Method 1
On the console, type for example:
link-region <Xloc> <Yloc> http://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 http://osl2.nac.uci.edu:9006/ with the URL (i.e. protocol, domain name/ip address, and 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 <Xloc> <Yloc> http://osl2.nac.uci.edu:9006/ UCI Welcome
The above syntax is the preferred one for this console command starting with revision r/14611 (commit 72748746; this will be in release 0.7.1). The following syntax was used before and is still supported but deprecated in current (development) versions of OpenSimulator:
link-region <Xloc> <Yloc> osl2.nac.uci.edu:9006or
link-region 997 997 osl2.nac.uci.edu:9006:UCI Welcome
Please note that this older syntax uses just the hostname without a protocol specification like http:// and a colon instead of a space to append a region name.
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/
Checking the 4096 Regions Limit
Due to the 4096 Regions Limit, there is a check in OpenSimulator since version 0.7.0.1 which verifies that the intended link will be within reach of any of your regions. If none of the regions in your grid or standalone is located within a distance radius of 4096 regions from the region to be linked, then the link will be rejected. You can disable this check in StandaloneCommon.ini (for standalones) or Robust.HG.ini (for grids) with
[GridService] Check4096 = false
Persistent Linked Regions
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
