OpenSimulator - User contributions [en]

User:UlyssesHirvi

2009-02-02T21:09:26Z

UlyssesHirvi: about me

Well here some details about the guy behind Ulysses, member of Hirvi.
The guy is:
- experienced in sl (2years +)
- Linux user
- mainframe system programmer and whatever you want to call it

- running regions connected to OSgrid
- running an own grid (remote accessible) and allowing a hyper-link from OSgrid (look for Port2Hirvi)
- running from build (svn) source
- saving trouble & electricity, so not up all the time

Main interest is the architecture of all this virtual world that is going on and
- willing to test
- willing to document (I did some additions to the Wiki)
- getting crazy about the arguments/parm/configuration of OpenSim
- separated ./regions/
- separated penSim.ini
- still wondering about the .xml's

contact in world or ulysses.hirvi at gmail.com

Hypergrid

2009-01-29T22:30:17Z

UlyssesHirvi: /* Linking regions */

==The OpenSim Hypergrid==

=== What is the hypergrid? ===


The hypergrid is an extension to opensim that allows you to link your opensim to other opensims on the internet, and that supports seamless agent transfers among those opensims. It can be used both in standalone mode and in grid mode. The hypergrid is effectively supporting the emergence of a Web of virtual worlds.

The basic idea for the hypergrid is that region/grid administrations can place hyperlinks on their map to hypergrided regions run by others. Once those hyperlinks are established, users interact with those regions in exactly the same way as they interact with local regions. Specifically, users can choose to teleport there. Once the user reaches the region behind the hyperlink, she is automatically interacting with a different virtual world without having to logout from the world where she came from, and while still having access to her inventory.

The hypergrid started as a GForge project, but it is now included in the standard distribution of OpenSim. To run your OpenSim instance in hypergrid mode, please see [[Hypergrid#Installing_and_Running_Hypergrid|Installing and Running]].

=== Virtual World Hyperlinks ===
[[image:hghyperlink.jpg|250px|thumb|A Virtual World Hyperlink]]

We're all familiar with hypertext links on the Web. But what is a virtual world hyperlink?

In the hypergrid model, we consider the 2D map of the virtual world as the equivalent of a web page. As such, a VW hyperlink is simply a region on that map.

The default model of opensim-based virtual worlds already supports this concept of hyperlink, to some extent. When you teleport from one region to another via the map, chances are you are migrating your agent into a different opensim server. This migration is a glorified "agent transfer" that also exists, in rudimentary form, on the web when hypertext links are followed. The default model, however, imposes two very strong constraints on these hyperlinks:
# The entire map of regions is controlled by a central service known as the grid service, whose job is to provide a uniform view of the world to all of its regions.
# The only agents that can be transferred are those pertaining to users known to another central service, the user service; if the incoming user is not on that service's database, the agent transfer doesn't go through.

The hypergrid simply removes these two constraints.

First, it allows individual opensim instances to add "neighbors" to their local map, shifting the control of the map down from the grid server to individual opensim instances (although hyperlinks can also be served by grid servers if grid admins so wish). In doing so, the world becomes a lot more interesting and varied. The map that you see in one opensim instance may be completely different from the map that you see after you teleport via an hyperlink. As an opensim administrator, you are free to define what other opensims you want to see on your map.

Second, it allows the transfer of agents pertaining to foreigner users, i.e. users who are registered elsewhere. Instead of assuming one central user service, the hypergrid assumes an arbitrarily large number of such services distributed all over the world. As such, when agents are transferred among hypergrided opensims, a lot more information is passed about the corresponding user. That information includes the collection of servers that the transferring user needs.

=== Usage Scenarios ===

The following are some usage scenarios. There isn't a clear separation between these scenarios, there's a large overlap between them. This is also not an exhaustive list. The purpose of these descriptions is to give you some starting ideas for how to use the hypergrid in practice. Please feel free to add other interesting scenarios to this list.

{| {{Prettytable}}
|-
|
[[image:topoA.jpg|400px|left]]
|
'''Personal Worlds'''

This first scenario pertains to standalone opensims. Normally, standalones are completely disconnected from the internet. However, when run in hypergrid mode, standalones become network-able. As such, you can run your own world in your own computer, and link your world to whoever you want. For example, you can link to your friends' hypergrided opensims and to hypergrid gateways in open grids such as OSGrid.

The great thing about this scenario is that all of your assets are stored on your computer, and not on somebody else's server. You can back them up using ordinary backend tools. The not so great thing about this scenario is that all of your assets are stored on your computer! If your disk goes berserk, you loose them. (so make sure you make external backups regularly)

|-
|
[[image:topoB.jpg|400px|left]]
|
'''Communities'''

This second scenario is about communities, broadly construed. The idea here is that a group of people come together to support a small community grid, i.e. a common world where shared activities take place. But at the same time, the members of the community maintain their own standalone worlds. The standalones link to the community grid, and the community grid may link back to the individual members' worlds and other places of interest.

The members' identities are probably the identities they have on their standalones, and their assets are also probably stored there. The assets present in the community regions, however, are stored on the grid asset server.

|-
|
[[image:topoC.jpg|400px|left]]
|
'''Grid Public Regions'''

Walled-gardens are here to stay, and they serve many useful purposes. There is a hybrid mode for the hypergrid that some walled-garden grid operators may be interested in supporting. In this hybrid mode, most opensim instances on the grid run in normal, wall-garden mode, so no foreign visitors are allowed there - technically it is impossible to reach them. However, a few opensim instances on that grid can run in hypergrid mode, so that foreign visitors are allowed. This way, there is a gateway for grid-local users and arbitrary visitors to meet. This is also a good strategy for attracting new users to the grid, since random users are able to visit those gateway regions without having to sign up for an account upfront.

This hybrid mode is very similar to what happens on the web. For example, anyone can visit Facebook's public pages without having to sign up for a Facebook account. However, only Facebook users can go further inside.

|-
|
[[image:topoD.jpg|400px|left]]
|
'''Level Games'''

The normal version of OpenSim enforces a common map for all the regions on a grid. The hypergrid removes that constraint. As such, it becomes easy to design VW games where the world looks different depending of where the player is.

|-
|}

== Security Concerns ==

There is a wide-spread assumption that open grids such as OSGrid and new forms of grids such as the hypergrid are inherently insecure, and that it will be impossible to develop a "goods-based" economy on top of them; only walled-gardens can be secured. This is both true and false. While it is true with the current state of things, open grids, whatever their form, can be made as secure as the web. The first step towards that is to define exactly what the security threats are, and how they affect (or not) open and closed grids. So, let's spell them out, and face them head-on. This will help put our feet on the ground so that we start developing appropriate solutions.

=== Malicious Clients ===

==== CopyBots ====

Everyone knows about the infamous [http://en.wikipedia.org/wiki/CopyBot CopyBot]. Using libraries such as [http://www.libsecondlife.org/wiki/Main_Page LibSL] (now known as OpenMetaverse) it is possible to develop clients for opensim servers that do unorthodox things such as bypassing the permissions system to copy people's assets. Bots written by griefers can do lots of other nasty things.

Malicious bots are a problem for all opensim administrators, including walled-garden grids. They can be prevented, to a certain extent, by exo-technical solutions such as Terms of Service and real-world lawsuits. Technically speaking, the only way to keep intruders out is to run opensim inside a firewall, pretty much like all other pieces of client/server software out there. If that's an acceptable solution for your case, you should do it.

Unfortunately firewalls also keep the public out, and most opensim operators, even the ones running walled-garden grids, want to reach out to the public. In this case, opensim operators may develop additional technical obstacles for bots, similar to those we see on the Web. For example, make sure agents are being run by real people by giving them a human-challenge during the login/TP process, etc.

Every obstacle to malicious clients lowers the risk of an intruder attack. However keep this in mind: no matter how many obstacles one builds, a sufficiently skilled and motivated attacker will be able to overcome them to penetrate opensims connected to the public internet. This affects hypergrid nodes as much as walled-garden grids. In fact, it's more pervasive than that: it affects '''all''' servers (opensim, web, etc.) connected to the public internet. Fighting malicious intruders is a fact of a connected world. Fortunately, those attacks don't happen very often, or the Web would have been dead by now.

==== Web Clients ====

CopyBots are the most well-known bots for opensim-based virtual worlds, but these virtual worlds are also susceptible to attacks by regular web clients. With the current state of things, it is actually easier to copy assets with a web-based client than with a libsl-based one. The weakness is that asset servers are connected to the public internet, and the protocol for interacting with them is public.

OpenSim has some minimal guards in place to fence against these kinds of attacks. Specifically, when the inventory server receives a request for an item, it checks the session identifier of the requester. Web clients aren't logged in, so they are refused service. I don't want to expand much more on this, so not to make life easy for attackers, but let's just say that opensim has the necessary mechanisms in place to fence off web-based attackers.

=== Malicious Hosts ===

==== Actively Malicious Hosts ====

The new security threat introduced by openness, one that does not exist in closed grids, is the possibility of a user to visit a region that is running malicious code. In the current state of opensim, a malicious host can do serious damage to the user's assets. Let's see how.

Assume you have your assets in your hypergrided-standalone opensim, and you go visit another opensim that happens to be running malicious code. Here is a non-exhaustive list of vulnerabilities that you are exposed to:

* The host has your session id, so it can request your inventory items on your behalf and store copies in its local asset server. To add insult to injury, a malicious host could simply wipe out your inventory after having copied it.
* Even if the malicious host doesn't access your items by itself, every time you access items in your inventory while you are in that region, those items are cached in the region's local cache, and can be stored persistently by the malicious host.

Malicious hosts can do a lot more damage, but those two are enough to illustrate this new kind of vulnerability affecting open grids. Note that this affects all open grids, i.e. those where arbitrary people can plug-in their opensims, and not just the hypergrid.

Fortunately, there is a family of simple solutions to this problem that can be summarized as "protecting you from yourself." That proposal is described [[Hypergrid Inventory Access|here]].

==== Piracy ====

A second new security threat affecting open grids is one pertaining to commerce of virtual goods. Suppose you put something out for sale on your hypergrided opensim. A foreign user comes and buys it. What that really means is that that user will physically get a copy of the assets moved to his/her asset server, which is different from your asset server. The permissions will be whatever you define them to be, and using the regular VW client, that user can only do what you defined he/she should could do with the object, as usual. However, if the user has direct backend access to the asset and inventory servers, that person can simply modify the permissions on his/her copy. This is commonly known as '''piracy'''. (This is also a problem with programmers who have direct access to the cache that their client keeps; in this case, the only thing that needs to be done to enable piracy is for the user to actually see a texture/animation/in-world object. This does NOT allow scripts to be copied, though, since the script is only interpreted on the server and is never sent for interpretation by the client.)

This situation is the kernel of the belief that open grids are hopeless for a virtual-goods economy. DRM discussion aside, maybe they are hopeless. But then, everyone thought the web was hopeless for selling music, and look at the success of iTunes in spite of all the piracy that still exists out there. Who will be the equivalent of iTunes for virtual hair, skin and clothes?

== Hypergrid Implementation ==

=== Hyperlinks and Agent Transfers ===

When you establish a link between your opensim and another, a message is sent out to that other opensim requesting information about it; the required information includes the network information of that opensim host, and the coordinates of its first region on its local grid in the form of a region handle. For example, suppose you are linking node X.com:9000, placing it in your local map at 900, 900. That opensim runs one or more regions that likely are not in 900, 900 on their own map; suppose the first region of that opensim is at 1100, 1100. From your point of view, it doesn't matter what those other coordinates are, and you don't need to know -- that's the key to being able to decentralize the "world" as given by a 2D map; you want to place it in your map at 900, 900. The "true" position of that simulator only matters for the LL viewer, when there are teleports between your world and that other opensim. This mapping between coordinate systems is the essence of hyperlinks for opensim; it's one simple but critical thing that the hypergrid implementation does. The mapping happens on the TeleportFinish event; instead of sending the local coordinates to the viewer, the hypergrid teleport wrapper sends the remote coordinates.

When an agent teleports through that hyperlink the following happens. First, before InformRegionOfChildAgent, the local opensim notifies the remote opensim of this foreign user via the "expect_hg_user" method. That message sends along the addresses of all the servers that this user uses, i.e. user, inventory and asset servers. The remote opensim places an entry for that user in its local user profile cache but not in its user database; the foreign user information is non-persistent. After that, the teleport process is exactly the same as the normal teleport process; the only difference is that the region handles are switched between the remote region's hyperlink position on the local grid and its actual position on its grid.

In summary, the two new concepts introduced by the hypergrid are the concept of an hyperlink and the concept of a "local user" vs. "foreign user".

=== Inventory Access ===

Inventory access from abroad is done by wrapping the existing scene-inventory interactions with additional code that gets or posts inventory assets from/to the user's asset server. When inventory is accessed, the hypergrid wrapper checks if the user is foreign and, if she is, the wrapper simply brings the necessary assets from the user's asset server to the local asset cache and server; from then on, the wrapper passes the control to the existing inventory access functions. When something is added to inventory, the hypergrid wrapper is notified via an event, and posts the assets to the user's asset server. A cache of the exchanged item identifiers is maintained so that they aren't brought back over and over again.

The result is that hypergrided opensim instances end up interacting with several asset servers, instead of just one. That interaction is implemented in a straightforward manner by instantiating several GridAssetClient objects, instead of just one.

=== The Hypergrid Namespace ===

Currently, the hypergrid is implemented outside of the OpenSim namespace, so that there is complete separation between what already exists and this new behavior. It has its own namespace, HyperGrid. In it, there are 4 sub-namespaces that follow directly the software architecture of OpenSim, namely:

* '''HyperGrid.Framework''' extends OpenSim.Framework in the following manner:
** HGUserProfileData extends UserProfileData by introducing information about the user's "home", namely the home address, port and remoting port. The user's home is not that user's user service; it's the opensim that the user has defined to be her home. This is necessary for supporting the home jump (Ctrl-Shift-H).
** HGNetworkServersInfo follows the spirit of NetworkServersInfo, although it neither extends it nor uses it. For now, it's a utility class whose two main functions are to convert domain names of servers to IP addresses, and to uniformly provide the answer to the question bool IsLocalUser(...).

* '''HyperGrid.Environment''' extends OpenSim.Region.Environment.Scenes in the following manner:
** HGSceneCommunicationService extends SceneCommunicationService, overriding RequestTeleportToLocation. There are two very small but critical changes to the base method: (a) on the TeleportFinish event, we switch the region handles when the destination region is an hyperlink; (b) the connections at the end are always closed for hyperlink TPs.
** HGScene extends Scene, overriding TeleportClientHome(...). The only change to the base method is to stay away from the user server, for now, because the user service is still not completely wrapped up for foreign users. Once the user service is properly wrapped up, this class will become unnecessary.
** HGScene.Inventory is a partial class of HGScene, just like what happens in the OpenSim framework. This part of HGScene overrides some inventory-scene interaction methods, so that assets are fetched/posted from/to the user's asset server. Once that extra fetching/posting is done, these methods simply pass the ball to the base methods.
** HGAssetMapper: this is a new class specific to the hypergrid that manages the fetching and posting of assets between foreign regions where the user is and the user's asset server.

* '''HyperGrid.Protocol''' is a mashup of OpenSim.Region.Communications.*. This is the place where most of the hypergrid extension lies. One of the reasons for this is that the hypergrid communications part is doing one additional thing: it is making standalones network-able.
** HGCommunicationsStandalone extends CommuniationsLocal. Just as its base, it is a hub for the several network services available in standalone mode. The main difference is that those services are extensions of what's in OpenSim.
** HGCommunicationsGridMode extends CommunicationsManager directly. Again, it's a hub for the network services available in grid mode, those services being extensions of OpenSim.
** The cluster HGGridServices (superclass), HGGridServicesStandalone and HGGridServicesGridMode (subclasses) implements the OpenSim interfaces IGridServices and IInterRegionCommunications. The 2 subclasses are wrappers for LocalBackEndServices and OGS1GridServices, respectively. There is one common pattern throughout these classes: check if the region to talk to is an hyperlink; if it's not, simply delegate the work to LocalBackEndServices/OGS1GridServices; if it is, push the work to the base class HGGridServices. HGGridServices, in turn, does the management of hyperlink regions, and defines two additional pieces of inter-region protocol:
*** region_uuid: for linking regions
*** expect_hg_user: similar to the existing expect_user interface, but with a lot more information about the user being passed around, namely all the user's servers (inventory, asset, user, home, etc.)
** HGInventoryService extends LocalInventoryService and implements ISecureInventoryService. This class is the most obvious mashup of the pack, mixing local service access for standalone users and remote inventory access for when users are out and about. Right now, there is a fair amount of selective copy-and-paste, to stay away from the ugliness coming from OGS1InventoryService and OGS1SecureInventoryService. HGInventoryService is always a ISecureInventoryService. Its methods all follow the same pattern: check if the user is a local standalone user; if it is, pass the work to the base method (in LocalInventoryService); if it's not perform secure remote access.
** HGUserServices wraps OSG1UserServices, but it's not functional yet.

* '''HyperGrid.Modules''' is a collection of 3 region modules:
** HGWorldMapModule extends WorldMapModule. It reuses almost everything from the base class. The only small change is in RequestMapBlocks, where it tries to send Offline mapblocks to the client.
** HGStandaloneInventoryService and HGStandaloneAssetService do what their names say. They are region modules that allow access to inventory and assets for standalones, when the standalone user is out and about. In spirit, there is a lot in common between these modules and the REST inventory/asset plugin. Unfortunately, that plugin could not be used because it defines a completely different interface than that used by existing inventory and asset servers, and the access for the hypergrid must use a consistent interface.

=== Class Diagram ===

[[image:HypergridImplementation.jpg|600px|center|(Click on the image to enlarge)]]

== Installing and Running Hypergrid ==

=== Installing ===

# Checkout OpenSim, prebuild and build as normal.
# Make the following changes to your OpenSim.ini:
#* The map: '''WorldMapModule = "HGWorldMap" ''' If you didn't have this setting in your original OpenSim.ini, make sure you place it under the [Startup] section.
#* If you're running your opensim in grid mode with the UGAIM servers on other machines, you're done. 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 <nowiki>"http://<external_host_name>:<http_port>"</nowiki>. See below.
# Run opensim like this: <nowiki>[mono] OpenSim.exe -hypergrid=true</nowiki>. To make sure the hypergrid is running type this on your console: '''link-region'''. If you don't hear anything back, the hypergrid is not properly installed.
'''[mono] OpenSim.exe -hypergrid=true'''

Here is an example of the Network settings for a standalone:

[Network]
http_listener_port = 9300
remoting_listener_port = 9895

grid_server_url = http://example.com:9300
grid_send_key = null
grid_recv_key = null

user_server_url = http://example.com:9300
user_send_key = null
user_recv_key = null

asset_server_url = http://example.com:9300
inventory_server_url = http://example.com:9300
messaging_server_url = http://example.com:9300

Here is an example of the Network settings for a grided opensim:

[Network]
http_listener_port = 9300
remoting_listener_port = 9895

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:8004
; Port 8005 reserved
messaging_server_url = http://example.com:8006

'''Important Note'''

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.

=== Linking regions ===
'''Method 1:'''

On the console, type for example:

link-region <Xloc> <Yloc> osl2.nac.uci.edu 9006 OSGrid Gateway

* 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 runing you want to link to

'''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>

I could then add my own region to the list with the section name "MW-Party". Then when I startup that region that I want to be part of this hypergrid, I use the command: "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.

*So: upgrade your own grid to which you want to link -the linkee- as above documented for OpenSim.ini.
*Than the region in p.e. OSGrid is started with hypergrid=true - the linker - and you add the command
- link-region X Y your.remote.accessible.grid your-port hyperregionname
*Be sure to have port (and NAT) all in line. And choose X Y on a free nearby location
* what I miss a "show-linkers" command"

'''Important Note'''

Due to a viewer [https://jira.secondlife.com/browse/SVC-2941 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.

== Public Hypergrid Nodes ==

Please see [[Public Hypergrid Nodes]].

== Hypergrid Lists ==
Please see [[Hypergrid Lists]].

Hypergrid

2009-01-25T19:04:21Z

UlyssesHirvi: /* Linking regions */

==The OpenSim Hypergrid==

=== What is the hypergrid? ===


The hypergrid is an extension to opensim that allows you to link your opensim to other opensims on the internet, and that supports seamless agent transfers among those opensims. It can be used both in standalone mode and in grid mode. The hypergrid is effectively supporting the emergence of a Web of virtual worlds.

The basic idea for the hypergrid is that region/grid administrations can place hyperlinks on their map to hypergrided regions run by others. Once those hyperlinks are established, users interact with those regions in exactly the same way as they interact with local regions. Specifically, users can choose to teleport there. Once the user reaches the region behind the hyperlink, she is automatically interacting with a different virtual world without having to logout from the world where she came from, and while still having access to her inventory.

The hypergrid started as a GForge project, but it is now included in the standard distribution of OpenSim. To run your OpenSim instance in hypergrid mode, please see [[Hypergrid#Installing_and_Running_Hypergrid|Installing and Running]].

=== Virtual World Hyperlinks ===
[[image:hghyperlink.jpg|250px|thumb|A Virtual World Hyperlink]]

We're all familiar with hypertext links on the Web. But what is a virtual world hyperlink?

In the hypergrid model, we consider the 2D map of the virtual world as the equivalent of a web page. As such, a VW hyperlink is simply a region on that map.

The default model of opensim-based virtual worlds already supports this concept of hyperlink, to some extent. When you teleport from one region to another via the map, chances are you are migrating your agent into a different opensim server. This migration is a glorified "agent transfer" that also exists, in rudimentary form, on the web when hypertext links are followed. The default model, however, imposes two very strong constraints on these hyperlinks:
# The entire map of regions is controlled by a central service known as the grid service, whose job is to provide a uniform view of the world to all of its regions.
# The only agents that can be transferred are those pertaining to users known to another central service, the user service; if the incoming user is not on that service's database, the agent transfer doesn't go through.

The hypergrid simply removes these two constraints.

First, it allows individual opensim instances to add "neighbors" to their local map, shifting the control of the map down from the grid server to individual opensim instances (although hyperlinks can also be served by grid servers if grid admins so wish). In doing so, the world becomes a lot more interesting and varied. The map that you see in one opensim instance may be completely different from the map that you see after you teleport via an hyperlink. As an opensim administrator, you are free to define what other opensims you want to see on your map.

Second, it allows the transfer of agents pertaining to foreigner users, i.e. users who are registered elsewhere. Instead of assuming one central user service, the hypergrid assumes an arbitrarily large number of such services distributed all over the world. As such, when agents are transferred among hypergrided opensims, a lot more information is passed about the corresponding user. That information includes the collection of servers that the transferring user needs.

=== Usage Scenarios ===

The following are some usage scenarios. There isn't a clear separation between these scenarios, there's a large overlap between them. This is also not an exhaustive list. The purpose of these descriptions is to give you some starting ideas for how to use the hypergrid in practice. Please feel free to add other interesting scenarios to this list.

{| {{Prettytable}}
|-
|
[[image:topoA.jpg|400px|left]]
|
'''Personal Worlds'''

This first scenario pertains to standalone opensims. Normally, standalones are completely disconnected from the internet. However, when run in hypergrid mode, standalones become network-able. As such, you can run your own world in your own computer, and link your world to whoever you want. For example, you can link to your friends' hypergrided opensims and to hypergrid gateways in open grids such as OSGrid.

The great thing about this scenario is that all of your assets are stored on your computer, and not on somebody else's server. You can back them up using ordinary backend tools. The not so great thing about this scenario is that all of your assets are stored on your computer! If your disk goes berserk, you loose them. (so make sure you make external backups regularly)

|-
|
[[image:topoB.jpg|400px|left]]
|
'''Communities'''

This second scenario is about communities, broadly construed. The idea here is that a group of people come together to support a small community grid, i.e. a common world where shared activities take place. But at the same time, the members of the community maintain their own standalone worlds. The standalones link to the community grid, and the community grid may link back to the individual members' worlds and other places of interest.

The members' identities are probably the identities they have on their standalones, and their assets are also probably stored there. The assets present in the community regions, however, are stored on the grid asset server.

|-
|
[[image:topoC.jpg|400px|left]]
|
'''Grid Public Regions'''

Walled-gardens are here to stay, and they serve many useful purposes. There is a hybrid mode for the hypergrid that some walled-garden grid operators may be interested in supporting. In this hybrid mode, most opensim instances on the grid run in normal, wall-garden mode, so no foreign visitors are allowed there - technically it is impossible to reach them. However, a few opensim instances on that grid can run in hypergrid mode, so that foreign visitors are allowed. This way, there is a gateway for grid-local users and arbitrary visitors to meet. This is also a good strategy for attracting new users to the grid, since random users are able to visit those gateway regions without having to sign up for an account upfront.

This hybrid mode is very similar to what happens on the web. For example, anyone can visit Facebook's public pages without having to sign up for a Facebook account. However, only Facebook users can go further inside.

|-
|
[[image:topoD.jpg|400px|left]]
|
'''Level Games'''

The normal version of OpenSim enforces a common map for all the regions on a grid. The hypergrid removes that constraint. As such, it becomes easy to design VW games where the world looks different depending of where the player is.

|-
|}

== Security Concerns ==

There is a wide-spread assumption that open grids such as OSGrid and new forms of grids such as the hypergrid are inherently insecure, and that it will be impossible to develop a "goods-based" economy on top of them; only walled-gardens can be secured. This is both true and false. While it is true with the current state of things, open grids, whatever their form, can be made as secure as the web. The first step towards that is to define exactly what the security threats are, and how they affect (or not) open and closed grids. So, let's spell them out, and face them head-on. This will help put our feet on the ground so that we start developing appropriate solutions.

=== Malicious Clients ===

==== CopyBots ====

Everyone knows about the infamous [http://en.wikipedia.org/wiki/CopyBot CopyBot]. Using libraries such as [http://www.libsecondlife.org/wiki/Main_Page LibSL] (now known as OpenMetaverse) it is possible to develop clients for opensim servers that do unorthodox things such as bypassing the permissions system to copy people's assets. Bots written by griefers can do lots of other nasty things.

Malicious bots are a problem for all opensim administrators, including walled-garden grids. They can be prevented, to a certain extent, by exo-technical solutions such as Terms of Service and real-world lawsuits. Technically speaking, the only way to keep intruders out is to run opensim inside a firewall, pretty much like all other pieces of client/server software out there. If that's an acceptable solution for your case, you should do it.

Unfortunately firewalls also keep the public out, and most opensim operators, even the ones running walled-garden grids, want to reach out to the public. In this case, opensim operators may develop additional technical obstacles for bots, similar to those we see on the Web. For example, make sure agents are being run by real people by giving them a human-challenge during the login/TP process, etc.

Every obstacle to malicious clients lowers the risk of an intruder attack. However keep this in mind: no matter how many obstacles one builds, a sufficiently skilled and motivated attacker will be able to overcome them to penetrate opensims connected to the public internet. This affects hypergrid nodes as much as walled-garden grids. In fact, it's more pervasive than that: it affects '''all''' servers (opensim, web, etc.) connected to the public internet. Fighting malicious intruders is a fact of a connected world. Fortunately, those attacks don't happen very often, or the Web would have been dead by now.

==== Web Clients ====

CopyBots are the most well-known bots for opensim-based virtual worlds, but these virtual worlds are also susceptible to attacks by regular web clients. With the current state of things, it is actually easier to copy assets with a web-based client than with a libsl-based one. The weakness is that asset servers are connected to the public internet, and the protocol for interacting with them is public.

OpenSim has some minimal guards in place to fence against these kinds of attacks. Specifically, when the inventory server receives a request for an item, it checks the session identifier of the requester. Web clients aren't logged in, so they are refused service. I don't want to expand much more on this, so not to make life easy for attackers, but let's just say that opensim has the necessary mechanisms in place to fence off web-based attackers.

=== Malicious Hosts ===

==== Actively Malicious Hosts ====

The new security threat introduced by openness, one that does not exist in closed grids, is the possibility of a user to visit a region that is running malicious code. In the current state of opensim, a malicious host can do serious damage to the user's assets. Let's see how.

Assume you have your assets in your hypergrided-standalone opensim, and you go visit another opensim that happens to be running malicious code. Here is a non-exhaustive list of vulnerabilities that you are exposed to:

* The host has your session id, so it can request your inventory items on your behalf and store copies in its local asset server. To add insult to injury, a malicious host could simply wipe out your inventory after having copied it.
* Even if the malicious host doesn't access your items by itself, every time you access items in your inventory while you are in that region, those items are cached in the region's local cache, and can be stored persistently by the malicious host.

Malicious hosts can do a lot more damage, but those two are enough to illustrate this new kind of vulnerability affecting open grids. Note that this affects all open grids, i.e. those where arbitrary people can plug-in their opensims, and not just the hypergrid.

Fortunately, there is a family of simple solutions to this problem that can be summarized as "protecting you from yourself." That proposal is described [[Hypergrid Inventory Access|here]].

==== Piracy ====

A second new security threat affecting open grids is one pertaining to commerce of virtual goods. Suppose you put something out for sale on your hypergrided opensim. A foreign user comes and buys it. What that really means is that that user will physically get a copy of the assets moved to his/her asset server, which is different from your asset server. The permissions will be whatever you define them to be, and using the regular VW client, that user can only do what you defined he/she should could do with the object, as usual. However, if the user has direct backend access to the asset and inventory servers, that person can simply modify the permissions on his/her copy. This is commonly known as '''piracy'''. (This is also a problem with programmers who have direct access to the cache that their client keeps; in this case, the only thing that needs to be done to enable piracy is for the user to actually see a texture/animation/in-world object. This does NOT allow scripts to be copied, though, since the script is only interpreted on the server and is never sent for interpretation by the client.)

This situation is the kernel of the belief that open grids are hopeless for a virtual-goods economy. DRM discussion aside, maybe they are hopeless. But then, everyone thought the web was hopeless for selling music, and look at the success of iTunes in spite of all the piracy that still exists out there. Who will be the equivalent of iTunes for virtual hair, skin and clothes?

== Hypergrid Implementation ==

=== Hyperlinks and Agent Transfers ===

When you establish a link between your opensim and another, a message is sent out to that other opensim requesting information about it; the required information includes the network information of that opensim host, and the coordinates of its first region on its local grid in the form of a region handle. For example, suppose you are linking node X.com:9000, placing it in your local map at 900, 900. That opensim runs one or more regions that likely are not in 900, 900 on their own map; suppose the first region of that opensim is at 1100, 1100. From your point of view, it doesn't matter what those other coordinates are, and you don't need to know -- that's the key to being able to decentralize the "world" as given by a 2D map; you want to place it in your map at 900, 900. The "true" position of that simulator only matters for the LL viewer, when there are teleports between your world and that other opensim. This mapping between coordinate systems is the essence of hyperlinks for opensim; it's one simple but critical thing that the hypergrid implementation does. The mapping happens on the TeleportFinish event; instead of sending the local coordinates to the viewer, the hypergrid teleport wrapper sends the remote coordinates.

When an agent teleports through that hyperlink the following happens. First, before InformRegionOfChildAgent, the local opensim notifies the remote opensim of this foreign user via the "expect_hg_user" method. That message sends along the addresses of all the servers that this user uses, i.e. user, inventory and asset servers. The remote opensim places an entry for that user in its local user profile cache but not in its user database; the foreign user information is non-persistent. After that, the teleport process is exactly the same as the normal teleport process; the only difference is that the region handles are switched between the remote region's hyperlink position on the local grid and its actual position on its grid.

In summary, the two new concepts introduced by the hypergrid are the concept of an hyperlink and the concept of a "local user" vs. "foreign user".

=== Inventory Access ===

Inventory access from abroad is done by wrapping the existing scene-inventory interactions with additional code that gets or posts inventory assets from/to the user's asset server. When inventory is accessed, the hypergrid wrapper checks if the user is foreign and, if she is, the wrapper simply brings the necessary assets from the user's asset server to the local asset cache and server; from then on, the wrapper passes the control to the existing inventory access functions. When something is added to inventory, the hypergrid wrapper is notified via an event, and posts the assets to the user's asset server. A cache of the exchanged item identifiers is maintained so that they aren't brought back over and over again.

The result is that hypergrided opensim instances end up interacting with several asset servers, instead of just one. That interaction is implemented in a straightforward manner by instantiating several GridAssetClient objects, instead of just one.

=== The Hypergrid Namespace ===

Currently, the hypergrid is implemented outside of the OpenSim namespace, so that there is complete separation between what already exists and this new behavior. It has its own namespace, HyperGrid. In it, there are 4 sub-namespaces that follow directly the software architecture of OpenSim, namely:

* '''HyperGrid.Framework''' extends OpenSim.Framework in the following manner:
** HGUserProfileData extends UserProfileData by introducing information about the user's "home", namely the home address, port and remoting port. The user's home is not that user's user service; it's the opensim that the user has defined to be her home. This is necessary for supporting the home jump (Ctrl-Shift-H).
** HGNetworkServersInfo follows the spirit of NetworkServersInfo, although it neither extends it nor uses it. For now, it's a utility class whose two main functions are to convert domain names of servers to IP addresses, and to uniformly provide the answer to the question bool IsLocalUser(...).

* '''HyperGrid.Environment''' extends OpenSim.Region.Environment.Scenes in the following manner:
** HGSceneCommunicationService extends SceneCommunicationService, overriding RequestTeleportToLocation. There are two very small but critical changes to the base method: (a) on the TeleportFinish event, we switch the region handles when the destination region is an hyperlink; (b) the connections at the end are always closed for hyperlink TPs.
** HGScene extends Scene, overriding TeleportClientHome(...). The only change to the base method is to stay away from the user server, for now, because the user service is still not completely wrapped up for foreign users. Once the user service is properly wrapped up, this class will become unnecessary.
** HGScene.Inventory is a partial class of HGScene, just like what happens in the OpenSim framework. This part of HGScene overrides some inventory-scene interaction methods, so that assets are fetched/posted from/to the user's asset server. Once that extra fetching/posting is done, these methods simply pass the ball to the base methods.
** HGAssetMapper: this is a new class specific to the hypergrid that manages the fetching and posting of assets between foreign regions where the user is and the user's asset server.

* '''HyperGrid.Protocol''' is a mashup of OpenSim.Region.Communications.*. This is the place where most of the hypergrid extension lies. One of the reasons for this is that the hypergrid communications part is doing one additional thing: it is making standalones network-able.
** HGCommunicationsStandalone extends CommuniationsLocal. Just as its base, it is a hub for the several network services available in standalone mode. The main difference is that those services are extensions of what's in OpenSim.
** HGCommunicationsGridMode extends CommunicationsManager directly. Again, it's a hub for the network services available in grid mode, those services being extensions of OpenSim.
** The cluster HGGridServices (superclass), HGGridServicesStandalone and HGGridServicesGridMode (subclasses) implements the OpenSim interfaces IGridServices and IInterRegionCommunications. The 2 subclasses are wrappers for LocalBackEndServices and OGS1GridServices, respectively. There is one common pattern throughout these classes: check if the region to talk to is an hyperlink; if it's not, simply delegate the work to LocalBackEndServices/OGS1GridServices; if it is, push the work to the base class HGGridServices. HGGridServices, in turn, does the management of hyperlink regions, and defines two additional pieces of inter-region protocol:
*** region_uuid: for linking regions
*** expect_hg_user: similar to the existing expect_user interface, but with a lot more information about the user being passed around, namely all the user's servers (inventory, asset, user, home, etc.)
** HGInventoryService extends LocalInventoryService and implements ISecureInventoryService. This class is the most obvious mashup of the pack, mixing local service access for standalone users and remote inventory access for when users are out and about. Right now, there is a fair amount of selective copy-and-paste, to stay away from the ugliness coming from OGS1InventoryService and OGS1SecureInventoryService. HGInventoryService is always a ISecureInventoryService. Its methods all follow the same pattern: check if the user is a local standalone user; if it is, pass the work to the base method (in LocalInventoryService); if it's not perform secure remote access.
** HGUserServices wraps OSG1UserServices, but it's not functional yet.

* '''HyperGrid.Modules''' is a collection of 3 region modules:
** HGWorldMapModule extends WorldMapModule. It reuses almost everything from the base class. The only small change is in RequestMapBlocks, where it tries to send Offline mapblocks to the client.
** HGStandaloneInventoryService and HGStandaloneAssetService do what their names say. They are region modules that allow access to inventory and assets for standalones, when the standalone user is out and about. In spirit, there is a lot in common between these modules and the REST inventory/asset plugin. Unfortunately, that plugin could not be used because it defines a completely different interface than that used by existing inventory and asset servers, and the access for the hypergrid must use a consistent interface.

=== Class Diagram ===

[[image:HypergridImplementation.jpg|600px|center|(Click on the image to enlarge)]]

== Installing and Running Hypergrid ==

=== Installing ===

# Checkout OpenSim, prebuild and build as normal.
# Make the following changes to your OpenSim.ini:
#* The map: '''WorldMapModule = "HGWorldMap" ''' If you didn't have this setting in your original OpenSim.ini, make sure you place it under the [Startup] section.
#* If you're running your opensim in grid mode with the UGAIM servers on other machines, you're done. 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 <nowiki>"http://<external_host_name>:<http_port>"</nowiki>. See below.
# Run opensim like this: <nowiki>[mono] OpenSim.exe -hypergrid=true</nowiki>. To make sure the hypergrid is running type this on your console: '''link-region'''. If you don't hear anything back, the hypergrid is not properly installed.
'''[mono] OpenSim.exe -hypergrid=true'''

Here is an example of the Network settings for a standalone:

[Network]
http_listener_port = 9300
remoting_listener_port = 9895

grid_server_url = http://example.com:9300
grid_send_key = null
grid_recv_key = null

user_server_url = http://example.com:9300
user_send_key = null
user_recv_key = null

asset_server_url = http://example.com:9300
inventory_server_url = http://example.com:9300
messaging_server_url = http://example.com:9300

Here is an example of the Network settings for a grided opensim:

[Network]
http_listener_port = 9300
remoting_listener_port = 9895

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:8004
; Port 8005 reserved
messaging_server_url = http://example.com:8006

'''Important Note'''

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.

=== Linking regions ===
'''Method 1:'''

On the console, type for example:

link-region <Xloc> <Yloc> osl2.nac.uci.edu 9006 OSGrid Gateway

* 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 port of the region you want to link to

'''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>

I could then add my own region to the list with the section name "MW-Party". Then when I startup that region that I want to be part of this hypergrid, I use the command: "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.

*So: upgrade your own grid to which you want to link -the linkee- as above documented for OpenSim.ini.
*Than the region in p.e. OSGrid is started with hypergrid=true - the linker - and you add the command
- link-region X Y your.remote.accessible.grid your-port hyperregionname
*Be sure to have port (and NAT) all in line. And choose X Y on a free nearby location
* what I miss is the link coming up in "show regions"

'''Important Note'''

Due to a viewer [https://jira.secondlife.com/browse/SVC-2941 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.

== Public Hypergrid Nodes ==

Please see [[Public Hypergrid Nodes]].

== Hypergrid Lists ==
Please see [[Hypergrid Lists]].

Configuration

2009-01-25T13:53:51Z

UlyssesHirvi: /* Standalone mode (local or remote)

== OpenSim Command line options ==
To run OpenSim in somewhat customized environments it's often helpful to modify the programs behaviour via command line arguments.
OpenSim knows a just a few of these as most parts of the behaviour are controlled via an .INI-File (see below).

The following command line switches are known:
{| border="1"
! Switch !! Meaning/Behaviour
|-
| inifile || changes the name (Path) of the inifile. See below for details
|-
| inimaster || allows to read in a master config file. See below for details
|-
| background || needs to be explained
|-
| gridmode || explain me
|-
| physics || explain me
|-
| useexecutepath || explain me
|-
| hypergrid || explain me
|}

==OpenSim configuration file==
The simulator configuration is managed using a file called [[OpenSim.ini]]. This file is used regardless of whether the sim is running in standalone or grid mode. Detailed information on the options available for setttings in this file can be found [[OpenSim.ini|here]].
Please note, that the name OpenSim.ini can be changed via command line arguments (see above).

It is also possible to distribute the inifile settings over two files. This is useful if you want to run several OpenSim processes where most of your settings are identical but some settings differ.
The master file is read first, then the inifile is read. Settings given in the inifile overrule settings given in the master file.
The master file has the same format and the same keywords as the inifile, so the same documentation applies.

== Logging ==
Usually you don't have a debugger and the source code at hand when a situation comes up. OpenSim does some logging to give you information about how it works.
This is done by use of the [http://logging.apache.org/log4net/index.html log4net-package]. The obvious console output of OpenSim as well as the OpenSim.log output are done via this package and come readily configured out of the box. But you can also make extended use of all other options this package can give you.

OpenSim makes use of the .NET System.Configuration API which means that the file that holds all the logging configuration is bin/OpenSim.exe.config .

More information on how to configure log4net can be found on the [http://logging.apache.org/log4net/release/manual/configuration.html log4net web pages].

==Database==
Opensim's supports the following database-engines:
* SQLite (default - a lightweight database that comes bundled with OpenSim and can be used without requiring any extra configuration. It is mostly intended to get you up and running quickly, not for production use.)
* MySQL (fully supported)
* MSSQL (partially supported - some recent OpenSim features may not yet be implemented)

More information on database support can be found on the [[OpenSim Database support]] page.

==Script engine==
OpenSim supports multiple script engines. See [[ScriptEngines]] for details

==Permissions Configuration==
OpenSim has a quite elaborate set of permissions. See [[OpenSim:Permissions(Server)]] for for details.

==Standalone vs. Grid==
We recommend that you first get OpenSim running in standalone mode before you attempt to connect it to a grid, either your own grid or a public grid. An OpenSim configuration consists of regions (run by region simulators) and 5 core backend services (which manage users, the grid, assets, inventories, and grid-wide messaging, collectively known as UGAIM).

A system running in '''standalone mode''' (that is, one with OpenSim.ini configured such that gridmode = false) -- also known as "sandbox mode" -- runs everything (all UGAIM services and one or more regions) in a single executable (OpenSim.exe). External regions cannot be added to an OpenSim running in this mode.

In '''grid mode''', the five services ([[User Server|User]], [[Grid Server|Grid]], [[Asset Server|Asset]], [[Inventory Server|Inventory]], [[Messaging Server|Messaging]], or UGAIM) are each started as separate executables. This means that they can be run either on the same machine or spread out across multiple computers. In this mode, OpenSim.exe serves one or more regions, which communicate with the core servers. This mode even allows region servers run by other people on their own machines to connect, if you wish.

Naturally, this means that running in grid mode is somewhat more complicated than running in standalone mode. It requires an understanding of UUID, X,Y location, server handshake passwords, master avatars, and a couple of other settings. These are not difficult, but do require a little more care in setting things up.

If you want to run a grid of your own (either private or public) you would start the core services up before connecting a region simulator. If you want to connect your region server to a grid that someone else is running, you need only start the region server in grid mode (with the necessary security keys and location information mentioned in the last paragraph).

OpenSim.exe responds to various command line arguments. These include "-inifile", "-configfile", "-gridmode", "-physics", "-config" & "-noverbose". When starting OpenSim in either Windows or Linux, one could, for example, add "-physics=OpenDynamicsEngine" to run the OpenDynamicsEngine instead of basicphysics, or use "-gridmode=true" to force opensim.exe to run as a region server (the rest of the grid services have their own executables). As many of these settings are normally controlled by OpenSim.ini, most users (especially in standalone mode) will not add any command line arguments.

===Standalone mode===

When you start OpenSim in standalone mode, it will ask you several questions at the console. The first set of prompts that start with "NETWORK SERVERS INFO", you can just hit return to accept the defaults if you will be running in standalone mode. The prompts that start with "DEFAULT REGION CONFIG" are where you need to start paying attention. Some are self-explanatory. Here are explanations for the others:<br>
* Grid Location. OpenSim regions can be placed anywhere on a 65536 by 65536 grid. In standalone mode, it is safe to leave these X and Y locations at their defaults for the first region (additional regions will need different coordinates, of course).
* Filename for local storage. Safe to leave at default.
* Internal IP address; This should always be 0.0.0.0 (0.0.0.0 means "listen for connections on any interface", basically a wildcard)
* Internal IP port for incoming UDP client connection. You can make this any port you want, but it is safe to leave at the default 9000.
* External host name. If you will only be attaching to your sim from a SecondLife client on the same machine, you can leave this at the default 127.0.0.1. If you will be wanting to connect to it from a client on another machine, this should be the IP address or hostname of the machine you are running this sim on. It appears that this must actually be the External Host IP Address, not the Domain Name. (Hmm - Tried hostname (the one resolved by dns) and it worked out oke.)
* Be aware of [http://osgrid.org/forums/viewtopic.php?f=5&t=400&start=0&st=0&sk=t&sd=a loopback] problems when Running viewer & server(s) on the same machine (LAN) but using the "external" configuration. (You might notice endless waiting for region handshake.) See also [http://opensimulator.org/wiki/Troubleshooting troubleshoot hints]
To connect to your new sim, start up secondlife with the following command line switches:
-loginuri http://127.0.0.1:9000/ -loginpage http://127.0.0.1:9000/?method=login
This assumes you are running the secondlife client on the same box. If you are running it on a separate box, substitute the IP address of your sim machine.<br>
To create a user:<br>
type ''create user <first> <last> <password> <x_loc> <y_loc>'' in the server console.

===Grid mode===
You want to run your own grid. Great! Assuming that you already got your sim running in standalone mode, here is what you need to do:<br>
1. Current builds of OpenSim grid mode are using mysql to store the grid information. You must have this installed and configured if you want to run your own grid. See [[mysql-config]] for more information.<br>
2. Four of the servers should be started in a certain order. UGAI: UserServer, GridServer, AssetServer, InventoryServer. The MessagingServer can be started at any point after the GridServer, and the RegionServer(s) should always come last. These are all found in the bin directory. In windows, you can just double-click on the executables to start them. In Linux and Mac OS X type "mono filename" from a prompt. The executable names, in order, are:
OpenSim.Grid.UserServer.exe
OpenSim.Grid.GridServer.exe
OpenSim.Grid.AssetServer.exe
OpenSim.Grid.InventoryServer.exe
OpenSim.Grid.MessagingServer.exe
OpenSim.exe
3. Start the UserServer. If you will be running the GridServer on the same box, hit enter to accept the defaults, until it gives you the prompt
OpenUser#
This is the main prompt for the user server. If you will be running the GridServer on another box, change the Default Grid Server URI as appropriate.<br>
4. Start the GridServer. Again, you can hit return at all the prompts if you are running them all on the same machine. If not, change the URIs for the Asset Server and User server to point to where you are running them. You will finally get to the console prompt for the GridServer which looks like this:
OpenGrid#
5. Start the AssetServer. The console prompt for this server will be:
OpenAsset#
6. Start the InventoryServer. The console prompt for this server will be:
INVENTORY#
7. Start the MessagingServer. The console prompt for this is:
Messaging#
8. If you are running all of these servers on the same box, which would be the normal configuration, you should be ready to start up your sim. The mode that OpenSim.exe starts in is normally controlled by a setting in your OpenSim.ini. It defaults to standalone mode if that setting is not specified or the file is not found. If you wish, you can force opensim to start in gridmode on the command line as follows:
OpenSim.exe -gridmode=true
or:
mono OpenSim.exe -gridmode=true
With any luck, everything will come up without too many errors.<br>
9. Go to the UserServer console, and type 'create user' to create a new avatar. It will prompt you for the name and password, and the X and Y of the sim that should be his home location. Use 1000 and 1000, or wherever you told your sim to live when you brought it up in standalone mode. At the console of any of these servers, you should be able to type 'help' to get a list of commands.

You should now be able to connect to your new grid with your secondlife client. You need to tell your client to point at the UserServer rather than directly at the sim, though:
secondlife -loginuri http://127.0.0.1:8002/
8002 is the default port for the UserServer, and that IP address should be changed to the server you are running the UserServer on, if they are not all on the same box. Happy OpenSimming!<br>
''Note: if you are using Windows Vista, remember to start servers as Admin. If not it will prompt you an error in console like "Error - Access denied"''

==Multiple regions==

Using Physical Prim with the OpenDynamicsEngine on *nix, it's recommended that you set your stack reserve level higher then default with the following command;
<tt>ulimit -s 262144</tt> Or, run the opensim-ode.sh to start up OpenSimulator.

A powerful region generator is available at: [[RegionGenerator]]

For running multiple regions on the same box, you simply make multiple copies of the 'default.xml' file inside the <tt>bin/Regions/</tt> directory. You can do this using the script <tt>make.php</tt> in <tt>share/regions</tt>, or you can generate the files by hand.

If you want to create the files by hand:

:first copy the default.xml file in the <tt>bin/Regions</tt> directory, and name them anything you want (I name mine region.x.y.xml, where region is the name of the region, and x and y are the grid coords.)
:Open each xml file and edit the uuid (a generator can be found at [http://www.famkruithof.net/uuid/uuidgen uuidgen webpage] or on unix, use the uuidgen command), region name, x & y positions, and internal ip port. IMPORTANT! The UUID, name, and grid coordinates ''must'' be unique for each region on a grid. The port assignment must be unique for each region that is running on a particular machine.<br>

Note that <tt>sim_location_x</tt> and <tt>sim_location_y</tt> should be adjacent integers if you want your regions to be adjacent, so you can run back and forth between them. '''IMPORTANT: THESE GRID COORDINATES ARE ''NOT'' IN METERS. THEY ARE SIM POSITIONS.''' (1000, 1000) is next to (1001,1000), (1000, 1001), and so forth. 1256, 2000, 2048 and similar values are '''not''' adjacent to 1000, they are very far away, so you would not see your sims from one another.

Once you have 2 or more xml files in the bin/Regions folder, running a ''single'' copy of <tt>OpenSim.exe</tt> will start up all of your sims! If you come across any errors, there is most likely an error in your xml files.

As of 6-Feb-2008, take care NOT to leave editor backup copies of the files in this directory e.g. emacs style backup names like Regionname.xml~. These are loaded by opensim.exe as if they are legitimate region descriptions, and will therefore give errors indicating you are trying to re-use the socket for that region.

==Attaching your sim to someone else's grid==
To set up the region server (i.e., <tt>OpenSim.exe</tt>) to connect to an external grid, you should edit the <tt>OpenSim.ini</tt> file in the <tt>bin</tt> directory. In that file, there is a <tt>[Network]</tt> section with URLs for the grid, user, and asset servers, as well as send and receive keys (for a basic level of security). The addresses and send/receive keys will vary depending on the grid you are connecting to, and the grid operator should tell you what values to use.

The other file you may have to change is in your <tt>bin/Regions</tt> directory. This is where your individual region config files are. If you only have one region, it will by default be called <tt>default.xml</tt>.

This can be edited with any text editor. The grid owner may tell you what X and Y location you can place your sim at (you can't have multiple sims at the same location on the grid). If so, the fields you will need to change in this file are <tt>sim_location_x</tt> and <tt>sim_location_y</tt>. And the <tt>external_host_name</tt> should be set to the hostname or IP address of your simulation server (i.e., the machine that is running <tt>OpenSim.exe</tt>).
A list of public grids that you can attach your sim to is at [[OpenSim: Grids]]

==Running==

===StandAlone===
'''<u>Windows</u>'''
cd bin
OpenSim.exe
On Windows Vista, it may be necessary to explicitly "Run as administrator" for opensim.exe to accept connections from a client, even when running as an administrator user. Navigate to the opensim\bin directory, right click opensim.exe, and select "Run as administrator".
Connect: opensim://localhost:9000 , or opensim://127.0.0.1:9000, or opensim://myipadress:9000

'''<u>Linux</u>'''
cd bin
mono OpenSim.exe

'''<u>OSX</u>'''
cd bin
mono OpenSim.exe

===Local Grid===
'''<u>Windows</u>'''
cd bin
OpenSim.Grid.UserServer.exe
OpenSim.Grid.GridServer.exe
OpenSim.Grid.AssetServer.exe
OpenSim.Grid.InventoryServer.exe
OpenSim.Grid.MessagingServer.exe
OpenSim.exe

'''<u>Linux</u>'''
cd bin
mono OpenSim.Grid.UserServer.exe
mono OpenSim.Grid.GridServer.exe
mono OpenSim.Grid.AssetServer.exe
mono OpenSim.Grid.InventoryServer.exe
mono OpenSim.Grid.MessagingServer.exe
mono OpenSim.exe

'''<u>OSX</u>''''
cd bin
mono OpenSim.Grid.UserServer.exe
mono OpenSim.Grid.GridServer.exe
mono OpenSim.Grid.AssetServer.exe
mono OpenSim.Grid.InventoryServer.exe
mono OpenSim.Grid.MessagingServer.exe
mono OpenSim.exe
Connect: opensim://myipaddress:9000

===Note About Mono===

If you're using mono, you should increase the value of the mono environment variable MONO_THREADS_PER_CPU from its default of 5 to some number that works for your sim. The exact number depends on many factors including: the number of CPUs in your machine, what else you use that machine for, how many regions you have in your sim, how many of them are adjacent, how many scripts you have, and how many avatars you expect to serve at the same time. As a reference, Wright Plaza in OSGrid, which is running as a single region on a sim and routinely hosts meetings with 20 avatars, uses the value 125.

If this number is too low, the operation of your sim will start to break in all sorts of different ways. A common symptom is the freezing of all activity upon login of a new avatar. Other symptoms are a lot more subtle.

== Configuration of region modules ==

* [[IRCBridgeModule]]

Configuration

2009-01-23T20:15:44Z

UlyssesHirvi: /* Standalone mode */ (remote)

== OpenSim Command line options ==
To run OpenSim in somewhat customized environments it's often helpful to modify the programs behaviour via command line arguments.
OpenSim knows a just a few of these as most parts of the behaviour are controlled via an .INI-File (see below).

The following command line switches are known:
{| border="1"
! Switch !! Meaning/Behaviour
|-
| inifile || changes the name (Path) of the inifile. See below for details
|-
| inimaster || allows to read in a master config file. See below for details
|-
| background || needs to be explained
|-
| gridmode || explain me
|-
| physics || explain me
|-
| useexecutepath || explain me
|-
| hypergrid || explain me
|}

==OpenSim configuration file==
The simulator configuration is managed using a file called [[OpenSim.ini]]. This file is used regardless of whether the sim is running in standalone or grid mode. Detailed information on the options available for setttings in this file can be found [[OpenSim.ini|here]].
Please note, that the name OpenSim.ini can be changed via command line arguments (see above).

It is also possible to distribute the inifile settings over two files. This is useful if you want to run several OpenSim processes where most of your settings are identical but some settings differ.
The master file is read first, then the inifile is read. Settings given in the inifile overrule settings given in the master file.
The master file has the same format and the same keywords as the inifile, so the same documentation applies.

== Logging ==
Usually you don't have a debugger and the source code at hand when a situation comes up. OpenSim does some logging to give you information about how it works.
This is done by use of the [http://logging.apache.org/log4net/index.html log4net-package]. The obvious console output of OpenSim as well as the OpenSim.log output are done via this package and come readily configured out of the box. But you can also make extended use of all other options this package can give you.

OpenSim makes use of the .NET System.Configuration API which means that the file that holds all the logging configuration is bin/OpenSim.exe.config .

More information on how to configure log4net can be found on the [http://logging.apache.org/log4net/release/manual/configuration.html log4net web pages].

==Database==
Opensim's supports the following database-engines:
* SQLite (default - a lightweight database that comes bundled with OpenSim and can be used without requiring any extra configuration. It is mostly intended to get you up and running quickly, not for production use.)
* MySQL (fully supported)
* MSSQL (partially supported - some recent OpenSim features may not yet be implemented)

More information on database support can be found on the [[OpenSim Database support]] page.

==Script engine==
OpenSim supports multiple script engines. See [[ScriptEngines]] for details

==Permissions Configuration==
OpenSim has a quite elaborate set of permissions. See [[OpenSim:Permissions(Server)]] for for details.

==Standalone vs. Grid==
We recommend that you first get OpenSim running in standalone mode before you attempt to connect it to a grid, either your own grid or a public grid. An OpenSim configuration consists of regions (run by region simulators) and 5 core backend services (which manage users, the grid, assets, inventories, and grid-wide messaging, collectively known as UGAIM).

A system running in '''standalone mode''' (that is, one with OpenSim.ini configured such that gridmode = false) -- also known as "sandbox mode" -- runs everything (all UGAIM services and one or more regions) in a single executable (OpenSim.exe). External regions cannot be added to an OpenSim running in this mode.

In '''grid mode''', the five services ([[User Server|User]], [[Grid Server|Grid]], [[Asset Server|Asset]], [[Inventory Server|Inventory]], [[Messaging Server|Messaging]], or UGAIM) are each started as separate executables. This means that they can be run either on the same machine or spread out across multiple computers. In this mode, OpenSim.exe serves one or more regions, which communicate with the core servers. This mode even allows region servers run by other people on their own machines to connect, if you wish.

Naturally, this means that running in grid mode is somewhat more complicated than running in standalone mode. It requires an understanding of UUID, X,Y location, server handshake passwords, master avatars, and a couple of other settings. These are not difficult, but do require a little more care in setting things up.

If you want to run a grid of your own (either private or public) you would start the core services up before connecting a region simulator. If you want to connect your region server to a grid that someone else is running, you need only start the region server in grid mode (with the necessary security keys and location information mentioned in the last paragraph).

OpenSim.exe responds to various command line arguments. These include "-inifile", "-configfile", "-gridmode", "-physics", "-config" & "-noverbose". When starting OpenSim in either Windows or Linux, one could, for example, add "-physics=OpenDynamicsEngine" to run the OpenDynamicsEngine instead of basicphysics, or use "-gridmode=true" to force opensim.exe to run as a region server (the rest of the grid services have their own executables). As many of these settings are normally controlled by OpenSim.ini, most users (especially in standalone mode) will not add any command line arguments.

===Standalone mode===

When you start OpenSim in standalone mode, it will ask you several questions at the console. The first set of prompts that start with "NETWORK SERVERS INFO", you can just hit return to accept the defaults if you will be running in standalone mode. The prompts that start with "DEFAULT REGION CONFIG" are where you need to start paying attention. Some are self-explanatory. Here are explanations for the others:<br>
* Grid Location. OpenSim regions can be placed anywhere on a 65536 by 65536 grid. In standalone mode, it is safe to leave these X and Y locations at their defaults for the first region (additional regions will need different coordinates, of course).
* Filename for local storage. Safe to leave at default.
* Internal IP address; This should always be 0.0.0.0 (0.0.0.0 means "listen for connections on any interface", basically a wildcard)
* Internal IP port for incoming UDP client connection. You can make this any port you want, but it is safe to leave at the default 9000.
* External host name. If you will only be attaching to your sim from a SecondLife client on the same machine, you can leave this at the default 127.0.0.1. If you will be wanting to connect to it from a client on another machine, this should be the IP address or hostname of the machine you are running this sim on. N.B - It appears that this must actually be the External Host IP Address, not the Domain Name.
N.B.- Tried hostname (the one resolved by dns) and it worked out oke.
N.B - Be aware of [http://osgrid.org/forums/viewtopic.php?f=5&t=400&start=0&st=0&sk=t&sd=a loopback] problems, p.e. if you run viewer & region on the same machine but using the "external" configuration. (Things you might notice is endless waiting for region handshake.)
To connect to your new sim, start up secondlife with the following command line switches:
-loginuri http://127.0.0.1:9000/ -loginpage http://127.0.0.1:9000/?method=login
This assumes you are running the secondlife client on the same box. If you are running it on a separate box, substitute the IP address of your sim machine.<br>
To create a user:<br>
type ''create user <first> <last> <password> <x_loc> <y_loc>'' in the server console.

===Grid mode===
You want to run your own grid. Great! Assuming that you already got your sim running in standalone mode, here is what you need to do:<br>
1. Current builds of OpenSim grid mode are using mysql to store the grid information. You must have this installed and configured if you want to run your own grid. See [[mysql-config]] for more information.<br>
2. Four of the servers should be started in a certain order. UGAI: UserServer, GridServer, AssetServer, InventoryServer. The MessagingServer can be started at any point after the GridServer, and the RegionServer(s) should always come last. These are all found in the bin directory. In windows, you can just double-click on the executables to start them. In Linux and Mac OS X type "mono filename" from a prompt. The executable names, in order, are:
OpenSim.Grid.UserServer.exe
OpenSim.Grid.GridServer.exe
OpenSim.Grid.AssetServer.exe
OpenSim.Grid.InventoryServer.exe
OpenSim.Grid.MessagingServer.exe
OpenSim.exe
3. Start the UserServer. If you will be running the GridServer on the same box, hit enter to accept the defaults, until it gives you the prompt
OpenUser#
This is the main prompt for the user server. If you will be running the GridServer on another box, change the Default Grid Server URI as appropriate.<br>
4. Start the GridServer. Again, you can hit return at all the prompts if you are running them all on the same machine. If not, change the URIs for the Asset Server and User server to point to where you are running them. You will finally get to the console prompt for the GridServer which looks like this:
OpenGrid#
5. Start the AssetServer. The console prompt for this server will be:
OpenAsset#
6. Start the InventoryServer. The console prompt for this server will be:
INVENTORY#
7. Start the MessagingServer. The console prompt for this is:
Messaging#
8. If you are running all of these servers on the same box, which would be the normal configuration, you should be ready to start up your sim. The mode that OpenSim.exe starts in is normally controlled by a setting in your OpenSim.ini. It defaults to standalone mode if that setting is not specified or the file is not found. If you wish, you can force opensim to start in gridmode on the command line as follows:
OpenSim.exe -gridmode=true
or:
mono OpenSim.exe -gridmode=true
With any luck, everything will come up without too many errors.<br>
9. Go to the UserServer console, and type 'create user' to create a new avatar. It will prompt you for the name and password, and the X and Y of the sim that should be his home location. Use 1000 and 1000, or wherever you told your sim to live when you brought it up in standalone mode. At the console of any of these servers, you should be able to type 'help' to get a list of commands.

You should now be able to connect to your new grid with your secondlife client. You need to tell your client to point at the UserServer rather than directly at the sim, though:
secondlife -loginuri http://127.0.0.1:8002/
8002 is the default port for the UserServer, and that IP address should be changed to the server you are running the UserServer on, if they are not all on the same box. Happy OpenSimming!<br>
''Note: if you are using Windows Vista, remember to start servers as Admin. If not it will prompt you an error in console like "Error - Access denied"''

==Multiple regions==

Using Physical Prim with the OpenDynamicsEngine on *nix, it's recommended that you set your stack reserve level higher then default with the following command;
<tt>ulimit -s 262144</tt> Or, run the opensim-ode.sh to start up OpenSimulator.

A powerful region generator is available at: [[RegionGenerator]]

For running multiple regions on the same box, you simply make multiple copies of the 'default.xml' file inside the <tt>bin/Regions/</tt> directory. You can do this using the script <tt>make.php</tt> in <tt>share/regions</tt>, or you can generate the files by hand.

If you want to create the files by hand:

:first copy the default.xml file in the <tt>bin/Regions</tt> directory, and name them anything you want (I name mine region.x.y.xml, where region is the name of the region, and x and y are the grid coords.)
:Open each xml file and edit the uuid (a generator can be found at [http://www.famkruithof.net/uuid/uuidgen uuidgen webpage] or on unix, use the uuidgen command), region name, x & y positions, and internal ip port. IMPORTANT! The UUID, name, and grid coordinates ''must'' be unique for each region on a grid. The port assignment must be unique for each region that is running on a particular machine.<br>

Note that <tt>sim_location_x</tt> and <tt>sim_location_y</tt> should be adjacent integers if you want your regions to be adjacent, so you can run back and forth between them. '''IMPORTANT: THESE GRID COORDINATES ARE ''NOT'' IN METERS. THEY ARE SIM POSITIONS.''' (1000, 1000) is next to (1001,1000), (1000, 1001), and so forth. 1256, 2000, 2048 and similar values are '''not''' adjacent to 1000, they are very far away, so you would not see your sims from one another.

Once you have 2 or more xml files in the bin/Regions folder, running a ''single'' copy of <tt>OpenSim.exe</tt> will start up all of your sims! If you come across any errors, there is most likely an error in your xml files.

As of 6-Feb-2008, take care NOT to leave editor backup copies of the files in this directory e.g. emacs style backup names like Regionname.xml~. These are loaded by opensim.exe as if they are legitimate region descriptions, and will therefore give errors indicating you are trying to re-use the socket for that region.

==Attaching your sim to someone else's grid==
To set up the region server (i.e., <tt>OpenSim.exe</tt>) to connect to an external grid, you should edit the <tt>OpenSim.ini</tt> file in the <tt>bin</tt> directory. In that file, there is a <tt>[Network]</tt> section with URLs for the grid, user, and asset servers, as well as send and receive keys (for a basic level of security). The addresses and send/receive keys will vary depending on the grid you are connecting to, and the grid operator should tell you what values to use.

The other file you may have to change is in your <tt>bin/Regions</tt> directory. This is where your individual region config files are. If you only have one region, it will by default be called <tt>default.xml</tt>.

This can be edited with any text editor. The grid owner may tell you what X and Y location you can place your sim at (you can't have multiple sims at the same location on the grid). If so, the fields you will need to change in this file are <tt>sim_location_x</tt> and <tt>sim_location_y</tt>. And the <tt>external_host_name</tt> should be set to the hostname or IP address of your simulation server (i.e., the machine that is running <tt>OpenSim.exe</tt>).
A list of public grids that you can attach your sim to is at [[OpenSim: Grids]]

==Running==

===StandAlone===
'''<u>Windows</u>'''
cd bin
OpenSim.exe
On Windows Vista, it may be necessary to explicitly "Run as administrator" for opensim.exe to accept connections from a client, even when running as an administrator user. Navigate to the opensim\bin directory, right click opensim.exe, and select "Run as administrator".
Connect: opensim://localhost:9000 , or opensim://127.0.0.1:9000, or opensim://myipadress:9000

'''<u>Linux</u>'''
cd bin
mono OpenSim.exe

'''<u>OSX</u>'''
cd bin
mono OpenSim.exe

===Local Grid===
'''<u>Windows</u>'''
cd bin
OpenSim.Grid.UserServer.exe
OpenSim.Grid.GridServer.exe
OpenSim.Grid.AssetServer.exe
OpenSim.Grid.InventoryServer.exe
OpenSim.Grid.MessagingServer.exe
OpenSim.exe

'''<u>Linux</u>'''
cd bin
mono OpenSim.Grid.UserServer.exe
mono OpenSim.Grid.GridServer.exe
mono OpenSim.Grid.AssetServer.exe
mono OpenSim.Grid.InventoryServer.exe
mono OpenSim.Grid.MessagingServer.exe
mono OpenSim.exe

'''<u>OSX</u>''''
cd bin
mono OpenSim.Grid.UserServer.exe
mono OpenSim.Grid.GridServer.exe
mono OpenSim.Grid.AssetServer.exe
mono OpenSim.Grid.InventoryServer.exe
mono OpenSim.Grid.MessagingServer.exe
mono OpenSim.exe
Connect: opensim://myipaddress:9000

===Note About Mono===

If you're using mono, you should increase the value of the mono environment variable MONO_THREADS_PER_CPU from its default of 5 to some number that works for your sim. The exact number depends on many factors including: the number of CPUs in your machine, what else you use that machine for, how many regions you have in your sim, how many of them are adjacent, how many scripts you have, and how many avatars you expect to serve at the same time. As a reference, Wright Plaza in OSGrid, which is running as a single region on a sim and routinely hosts meetings with 20 avatars, uses the value 125.

If this number is too low, the operation of your sim will start to break in all sorts of different ways. A common symptom is the freezing of all activity upon login of a new avatar. Other symptoms are a lot more subtle.

== Configuration of region modules ==

* [[IRCBridgeModule]]

Talk:Configuration

2009-01-22T21:45:53Z

UlyssesHirvi: New page: Hi I'm sorry, just did a section edit view and save .... and the result is a lot of loss. Please restore the original and add the remark about loopback when using external hsot configurat...

Hi I'm sorry, just did a section edit view and save .... and the result is a lot of loss.

Please restore the original and add the remark about loopback when using external hsot configuration

Configuration

2009-01-22T21:40:53Z

UlyssesHirvi: NAT problems

===Standalone mode===

When you start OpenSim in standalone mode, it will ask you several questions at the console. The first set of prompts that start with "NETWORK SERVERS INFO", you can just hit return to accept the defaults if you will be running in standalone mode. The prompts that start with "DEFAULT REGION CONFIG" are where you need to start paying attention. Some are self-explanatory. Here are explanations for the others:<br>
* Grid Location. OpenSim regions can be placed anywhere on a 65536 by 65536 grid. In standalone mode, it is safe to leave these X and Y locations at their defaults for the first region (additional regions will need different coordinates, of course).
* Filename for local storage. Safe to leave at default.
* Internal IP address; This should always be 0.0.0.0 (0.0.0.0 means "listen for connections on any interface", basically a wildcard)
* Internal IP port for incoming UDP client connection. You can make this any port you want, but it is safe to leave at the default 9000.
* External host name. If you will only be attaching to your sim from a SecondLife client on the same machine, you can leave this at the default 127.0.0.1. If you will be wanting to connect to it from a client on another machine, this should be the IP address or hostname of the machine you are running this sim on. N.B - It appears that this must actually be the External Host IP Address, not the Domain Name.
* If configuring "External Host Name" (you can use the host name is my experience) and running viewer and server on the same machine (or LAN when using wan-ip and port-forwarding) create a [http://osgrid.org/forums/viewtopic.php?f=5&t=400&start=0&st=0&sk=t&sd=a loopback]
To connect to your new sim, start up secondlife with the following command line switches:
-loginuri http://127.0.0.1:9000/ -loginpage http://127.0.0.1:9000/?method=login
This assumes you are running the secondlife client on the same box. If you are running it on a separate box, substitute the IP address of your sim machine.<br>
To create a user:<br>
type ''create user <first> <last> <password> <x_loc> <y_loc>'' in the server console.

Tips

2008-08-30T21:23:44Z

UlyssesHirvi: /* Placing data away from the code */

[[Category:Users]]
==Terrain Tidbits==
===How can I flatten a region?===
When you have multiple regions, that you need to terraform to a certain height, the quickest way to do it is by selecting a region, and fill the terrain to the specified height:
change-region YourRegionName
script terrain fill 20

''Note:'' Remember to change to the region you wish to modify if that is the only region wish to make changes to. Without using the change-region command, you may very well end up flattening multiple regions!

As of SVN 4061
terrain fill 25

[[Category:Getting Started]]

=== What programs can I use to create terrains for OpenSim? ===
If you are after simple terrain files (jpg, gif, etc), you can use Photoshop or any number of freeware programs, like [http://www.gimp.org/ Gimp]. If you want more complex terrains, you will need programs that output to standard 3d raw format (aka r32 or r64). [http://www.bundysoft.com/L3DT/ L3DT] and [http://www.planetside.co.uk/terragen/ Terragen] are two of the top commercial programs for this. (anyone know of a freeware one?), or you could, with some practice, use [http://www.blender.org/ Blender]. The free version of L3DT can make terrains up to 2048x2048 in size, or 8x8 regions.
You can use `terrain load IMG yourfile.png` to load '''greyscale''' PNG files. Remember to use something like `terrain rescale 0 25` to make it visible.
Here is some info on [[Using L3DT]] to make a terrain.

You can also use http://lab.parkstudio.ru/terra/ if you know a bit about heightmaps and how they work. Just set the custom landscape texture gradient to pure black and pure white and turn off water.
And here are some [[Free Terrains]] that you can use. Enjoy!

=== Where do I put the files for my terrains? ===
This one is actually pretty simple, but first the 'hard' answer: anywhere in the PATH will work. Lost? yeah, I was too, so... just drop the file into the <tt>bin</tt> directory (right where your <tt>OpenSim.exe</tt> file is).

===How do I change the terrain for a group of sims?===
First, the file must be in f32 (or f64?) format. This is easy to do with L3DT's export feature. (Use the RAW format and set the options to <tt>Y flipped = true</tt> and at the bottom, change it to read 'float' instead of 'ushort'). It also needs to be a file that will cover each sim in a 256x256 layer (so, for 2x2 regions, you need a 512x512 file), It is very important that you rename the file extension to .r32 for the import to properly work.
Then, once you have it saved, on the <tt>OpenSim.exe</tt> console, type in:
script terrain load-tile <filename> <image X> <image y> <bottomleftsim X> <bottomleftsim y>
For example, I run a square of 4 sims in a 2x2 pattern. I started my sim placement at 0, 0 and ended at 1, 1. my line reads:
<strike>script terrain load-tile simalpha.r32 512 512 0 0</strike>
script terrain load-tile simalpha.r32 2 2 0 0 ([[User:Oudrun|Oudrun]])
New syntax is using number of tiles instead of imagesize (one tile 256x356 pix). Above example is for a 2x2 region terrainfile.

Next, before you log in, you may want to go to type in: *(THIS FUNCTION MAY NOT WORK)
script terrain multiply 0.4
This should scale it down from the nearly 300 meters altitude I ran into to something a little more reasonable for the minimap.

===How do I load a terrain file on startup?===
Edit the file <tt>startup_commands.txt</tt> in the bin directory and add the above commands "<tt>script terrain load-tile ...</tt>" and "<tt>script terrain multiply ...</tt>" one per line.

*** Notice this method is no longer required and should be considered a legacy function, Terrain persistance is now working 100%.

Terrain Tidbits brought to you by Tilde, with a few questions in IRC :) - [[User:Tildeampersand|Tilde]] 10:32, 15 August 2007 (PDT)

===How do I import into OpenSim the terrain shape of my Second Life sim?===
First, assure you are in the right region if you have more than one, by using:

change-region <nowiki><regionname></nowiki>

Then use the command (file extension now determines the format, use .r32 for L3DT terrains)

script terrain load <filename>

Watch [http://archimedix.wordpress.com/2007/11/26/opensim/ this video] for a step-by-step tutorial.

=== Other useless or useful info depending on who reads it ===

* I found out that each point on the grey scale (0 to 255) equals approximately .23 to .25 meters in terrain height. - [[CharlieO]]
* Also for those who want to manually edit a png file, you need at minimum 3 different shades of grey. and one has to be drastically different than the other 2 in order to have the height show correctly. - [[CharlieO]]
example:
1) 0,0,0
2) 223, 233, 233
3) 255, 255, 255

==General Setup Tricks==
=== Changing viewer start webpage in standalone mode ===

In order to change the page that the viewer starts in /opensim/bin/ there is a http_loginform.html.example page. Removing the .example will make this page be the start webpage which you can edit etc. Since the login html code is no longer needed this can be modified at will.

=== Making the server remember terrain, prims and other region storage changes after reboot ===
In order for the server to remember these things you must select a database to be used in the OpenSim.ini file. For more info on setting this up see [[OpenSim_Database_support]]. The easiest to set up is SqLite which has a guide on the linked page.

=== Placing data away from the code ===
A good set up, separates the code (replaced often in this project) from the data ("unique" and more valuable for the user). Things to do:
* separate your region definitions by using the ''regionload_regionsdir'' value in the OpenSim.ini
e.g. regionload_regionsdir="../OSHirvi/Regions" places the Regions directory besides the "code directory" in a folder called OSHirvi
* make your data persistent in a database (see above), this requires (again) to edit your OpenSim.ini file. You might use unique names to separate multiple setups within the database server you use.
e.g. ''storage_connection_string=''"Data Source=localhost;Database=OSHirvi;User ID=OSHirvi;Password=password;";
* the next step is copying/cutting OpenSim.ini itself away from the code
p.e. place this file in ../OSHirvi/OpenSim.1.ini
* to point from your place ../ to your wanted runtime directory create a link (or some call it shortcut). If you download a newer build just change the link.
e.g. ln -s opensimservercode opensim-0.5.8.5695

Now create a script, and call it startHirvi.sh that:
a) gets it current directory in the code directory, found by the link
b) starts up OpenSim.exe with the required .ini file, by using the ''-inifile'' startup option. You can still add other options.
cd ../opensimservercode
mono OpenSim.exe -inifile ../OSHirvi/OpenSim.1.ini -gridmode=true

Oke, done this you are left with a code directory still filled with runtime data, but this is just persistent temporary stuff that the server automatic rebuilds if it is deleted. Still a pitty there is no way to get it separate.
./addin-db-00
./addins
./OpaenSim.log and many others if you run in grid-mode
./estate_settings.xml and many other configuration settings

Talk:Tips

2008-08-26T20:27:03Z

UlyssesHirvi: New page: Anyone more to contribute to my section Place data away from the code. Be welcme and help me (Ulysses Hirvi) out.

Anyone more to contribute to my section Place data away from the code. Be welcme and help me (Ulysses Hirvi) out.

Tips

2008-08-26T20:25:04Z

UlyssesHirvi: Placing data away from code, good habbits

[[Category:Users]]
==Terrain Tidbits==
===How can I flatten a region?===
When you have multiple regions, that you need to terraform to a certain height, the quickest way to do it is by selecting a region, and fill the terrain to the specified height:
change-region YourRegionName
script terrain fill 20

''Note:'' Remember to change to the region you wish to modify if that is the only region wish to make changes to. Without using the change-region command, you may very well end up flattening multiple regions!

As of SVN 4061
terrain fill 25

[[Category:Getting Started]]

=== What programs can I use to create terrains for OpenSim? ===
If you are after simple terrain files (jpg, gif, etc), you can use Photoshop or any number of freeware programs, like [http://www.gimp.org/ Gimp]. If you want more complex terrains, you will need programs that output to standard 3d raw format (aka r32 or r64). [http://www.bundysoft.com/L3DT/ L3DT] and [http://www.planetside.co.uk/terragen/ Terragen] are two of the top commercial programs for this. (anyone know of a freeware one?), or you could, with some practice, use [http://www.blender.org/ Blender]. The free version of L3DT can make terrains up to 2048x2048 in size, or 8x8 regions.
You can use `terrain load IMG yourfile.png` to load '''greyscale''' PNG files. Remember to use something like `terrain rescale 0 25` to make it visible.
Here is some info on [[Using L3DT]] to make a terrain.

You can also use http://lab.parkstudio.ru/terra/ if you know a bit about heightmaps and how they work. Just set the custom landscape texture gradient to pure black and pure white and turn off water.
And here are some [[Free Terrains]] that you can use. Enjoy!

=== Where do I put the files for my terrains? ===
This one is actually pretty simple, but first the 'hard' answer: anywhere in the PATH will work. Lost? yeah, I was too, so... just drop the file into the <tt>bin</tt> directory (right where your <tt>OpenSim.exe</tt> file is).

===How do I change the terrain for a group of sims?===
First, the file must be in f32 (or f64?) format. This is easy to do with L3DT's export feature. (Use the RAW format and set the options to <tt>Y flipped = true</tt> and at the bottom, change it to read 'float' instead of 'ushort'). It also needs to be a file that will cover each sim in a 256x256 layer (so, for 2x2 regions, you need a 512x512 file), It is very important that you rename the file extension to .r32 for the import to properly work.
Then, once you have it saved, on the <tt>OpenSim.exe</tt> console, type in:
script terrain load-tile <filename> <image X> <image y> <bottomleftsim X> <bottomleftsim y>
For example, I run a square of 4 sims in a 2x2 pattern. I started my sim placement at 0, 0 and ended at 1, 1. my line reads:
<strike>script terrain load-tile simalpha.r32 512 512 0 0</strike>
script terrain load-tile simalpha.r32 2 2 0 0 ([[User:Oudrun|Oudrun]])
New syntax is using number of tiles instead of imagesize (one tile 256x356 pix). Above example is for a 2x2 region terrainfile.

Next, before you log in, you may want to go to type in: *(THIS FUNCTION MAY NOT WORK)
script terrain multiply 0.4
This should scale it down from the nearly 300 meters altitude I ran into to something a little more reasonable for the minimap.

===How do I load a terrain file on startup?===
Edit the file <tt>startup_commands.txt</tt> in the bin directory and add the above commands "<tt>script terrain load-tile ...</tt>" and "<tt>script terrain multiply ...</tt>" one per line.

*** Notice this method is no longer required and should be considered a legacy function, Terrain persistance is now working 100%.

Terrain Tidbits brought to you by Tilde, with a few questions in IRC :) - [[User:Tildeampersand|Tilde]] 10:32, 15 August 2007 (PDT)

===How do I import into OpenSim the terrain shape of my Second Life sim?===
First, assure you are in the right region if you have more than one, by using:

change-region <nowiki><regionname></nowiki>

Then use the command (file extension now determines the format, use .r32 for L3DT terrains)

script terrain load <filename>

Watch [http://archimedix.wordpress.com/2007/11/26/opensim/ this video] for a step-by-step tutorial.

=== Other useless or useful info depending on who reads it ===

* I found out that each point on the grey scale (0 to 255) equals approximately .23 to .25 meters in terrain height. - [[CharlieO]]
* Also for those who want to manually edit a png file, you need at minimum 3 different shades of grey. and one has to be drastically different than the other 2 in order to have the height show correctly. - [[CharlieO]]
example:
1) 0,0,0
2) 223, 233, 233
3) 255, 255, 255

==General Setup Tricks==
=== Changing viewer start webpage in standalone mode ===

In order to change the page that the viewer starts in /opensim/bin/ there is a http_loginform.html.example page. Removing the .example will make this page be the start webpage which you can edit etc. Since the login html code is no longer needed this can be modified at will.

=== Making the server remember terrain, prims and other region storage changes after reboot ===
In order for the server to remember these things you must select a database to be used in the OpenSim.ini file. For more info on setting this up see [[OpenSim_Database_support]]. The easiest to set up is SqLite which has a guide on the linked page.

=== Placing data away from the code ===
A good set up, separates the code (replaced often in this project) from the data ("unique" and more valuable for the user). Things to do:
* separate your region definitions by using the ''regionload_regionsdir'' value in the OpenSim.ini
p.e. regionload_regionsdir="../OSHirvi/Regions" places the Regions directory besides the "code directory" in a folder called OSHirvi
* make your data persistent in a database (see above), this requires (again) to edit your OpenSim.ini file. You might use unique names to separate multiple setups within the database server you use.
p.e. ''storage_connection_string=''"Data Source=localhost;Database=OSHirvi;User ID=OSHirvi;Password=password;";
* the next step is copying/cutting OpenSim.ini itself away from the code
p.e. place this file in ../OSHirvi/OpenSim.1.ini
* to point from your place ../ to your wanted runtime directory create a link (or some call it shortcut). If you download a newer build just change the link.
p.e. ln -s opensimservercode opensim-0.5.8.5695

Now create a script, and call it startHirvi.sh that:
a) gets it current directory in the code directory, found by the link
b) starts up OpenSim.exe with the required .ini file, by using the ''-inifile'' startup option. You can still add other options.
cd ../opensimservercode
mono OpenSim.exe -inifile ../OSHirvi/OpenSim.1.ini -gridmode=true

Oke, done this you are left with a code directory still filled with runtime data, but this is just persistent temporary stuff that the server automatic rebuilds if it is deleted. Still a pitty there is no way to get it separate.
./addin-db-00
./addins
./OpenSim.log and many others if you run in grid-mode
./estate_settings.xml and many other configuration settings

Tips

2008-08-26T19:49:42Z

UlyssesHirvi: /* General Setup Tricks */

[[Category:Users]]
==Terrain Tidbits==
===How can I flatten a region?===
When you have multiple regions, that you need to terraform to a certain height, the quickest way to do it is by selecting a region, and fill the terrain to the specified height:
change-region YourRegionName
script terrain fill 20

''Note:'' Remember to change to the region you wish to modify if that is the only region wish to make changes to. Without using the change-region command, you may very well end up flattening multiple regions!

As of SVN 4061
terrain fill 25

[[Category:Getting Started]]

=== What programs can I use to create terrains for OpenSim? ===
If you are after simple terrain files (jpg, gif, etc), you can use Photoshop or any number of freeware programs, like [http://www.gimp.org/ Gimp]. If you want more complex terrains, you will need programs that output to standard 3d raw format (aka r32 or r64). [http://www.bundysoft.com/L3DT/ L3DT] and [http://www.planetside.co.uk/terragen/ Terragen] are two of the top commercial programs for this. (anyone know of a freeware one?), or you could, with some practice, use [http://www.blender.org/ Blender]. The free version of L3DT can make terrains up to 2048x2048 in size, or 8x8 regions.
You can use `terrain load IMG yourfile.png` to load '''greyscale''' PNG files. Remember to use something like `terrain rescale 0 25` to make it visible.
Here is some info on [[Using L3DT]] to make a terrain.

You can also use http://lab.parkstudio.ru/terra/ if you know a bit about heightmaps and how they work. Just set the custom landscape texture gradient to pure black and pure white and turn off water.
And here are some [[Free Terrains]] that you can use. Enjoy!

=== Where do I put the files for my terrains? ===
This one is actually pretty simple, but first the 'hard' answer: anywhere in the PATH will work. Lost? yeah, I was too, so... just drop the file into the <tt>bin</tt> directory (right where your <tt>OpenSim.exe</tt> file is).

===How do I change the terrain for a group of sims?===
First, the file must be in f32 (or f64?) format. This is easy to do with L3DT's export feature. (Use the RAW format and set the options to <tt>Y flipped = true</tt> and at the bottom, change it to read 'float' instead of 'ushort'). It also needs to be a file that will cover each sim in a 256x256 layer (so, for 2x2 regions, you need a 512x512 file), It is very important that you rename the file extension to .r32 for the import to properly work.
Then, once you have it saved, on the <tt>OpenSim.exe</tt> console, type in:
script terrain load-tile <filename> <image X> <image y> <bottomleftsim X> <bottomleftsim y>
For example, I run a square of 4 sims in a 2x2 pattern. I started my sim placement at 0, 0 and ended at 1, 1. my line reads:
<strike>script terrain load-tile simalpha.r32 512 512 0 0</strike>
script terrain load-tile simalpha.r32 2 2 0 0 ([[User:Oudrun|Oudrun]])
New syntax is using number of tiles instead of imagesize (one tile 256x356 pix). Above example is for a 2x2 region terrainfile.

Next, before you log in, you may want to go to type in: *(THIS FUNCTION MAY NOT WORK)
script terrain multiply 0.4
This should scale it down from the nearly 300 meters altitude I ran into to something a little more reasonable for the minimap.

===How do I load a terrain file on startup?===
Edit the file <tt>startup_commands.txt</tt> in the bin directory and add the above commands "<tt>script terrain load-tile ...</tt>" and "<tt>script terrain multiply ...</tt>" one per line.

*** Notice this method is no longer required and should be considered a legacy function, Terrain persistance is now working 100%.

Terrain Tidbits brought to you by Tilde, with a few questions in IRC :) - [[User:Tildeampersand|Tilde]] 10:32, 15 August 2007 (PDT)

===How do I import into OpenSim the terrain shape of my Second Life sim?===
First, assure you are in the right region if you have more than one, by using:

change-region <nowiki><regionname></nowiki>

Then use the command (file extension now determines the format, use .r32 for L3DT terrains)

script terrain load <filename>

Watch [http://archimedix.wordpress.com/2007/11/26/opensim/ this video] for a step-by-step tutorial.

=== Other useless or useful info depending on who reads it ===

* I found out that each point on the grey scale (0 to 255) equals approximately .23 to .25 meters in terrain height. - [[CharlieO]]
* Also for those who want to manually edit a png file, you need at minimum 3 different shades of grey. and one has to be drastically different than the other 2 in order to have the height show correctly. - [[CharlieO]]
example:
1) 0,0,0
2) 223, 233, 233
3) 255, 255, 255

==General Setup Tricks==
=== Changing viewer start webpage in standalone mode ===

In order to change the page that the viewer starts in /opensim/bin/ there is a http_loginform.html.example page. Removing the .example will make this page be the start webpage which you can edit etc. Since the login html code is no longer needed this can be modified at will.

=== Making the server remember terrain, prims and other region storage changes after reboot ===
In order for the server to remember these things you must select a database to be used in the OpenSim.ini file. For more info on setting this up see [[OpenSim_Database_support]]. The easiest to set up is SqLite which has a guide on the linked page.

=== Placing data away from the code ===
A good set up, separates the code (replaced often in this project) from the data ("unique" and more valuable for the user). Things to do:
* separate your region definitions by using the ''regionload_regionsdir'' value in the OpenSim.ini
p.e. regionload_regionsdir="../OSHirvi/Regions" places the Regions directory besides the "code directory" in a folder called OSHirvi
* make your data persistent in a database (see above), this requires (again) to edit your OpenSim.ini file. You might use unique names to separate multiple setups within the database server you use.
p.e. ''storage_connection_string=''"Data Source=localhost;Database=OSHirvi;User ID=OSHirvi;Password=password;";
* the next step is copying/cutting OpenSim.ini itself away from the code
p.e. place this file in ../OSHirvi/OpenSim.1.ini
* to point from your place ../ to your wanted runtime directory create a link (or some call it shortcut). If you download a newer build just change the link.
p.e. ln -s opensimservercode opensim-0.5.8.5695

Now create a script, and call it startHirvi.sh that:
a) gets it current directory in the code directory, found by the link
b) starts up OpenSim.exe with the required .ini file, by using the ''-inifile'' startup option. You can still add other options.
cd ../opensimservercode
mono OpenSim.exe -inifile ../OSHirvi/OpenSim.1.ini -gridmode=true