How To Enable Kitely Market in Non-Hypergrid Grids

Owned by Oren Hurvitz
Last updated: Apr 20, 2020 by Ilan Tochner
6 min read

Overview

This document explains how to enable delivery from Kitely Market to grids that aren't open to the Hypergrid. The target audience is grid managers.

We will do the following:

  • Enable a few Hypergrid services

  • Use the firewall to allow access only from Kitely

Since the grid is non-Hypergrid, we assume that it's currently using the configuration file Robust.ini. That is the only configuration file that will be modified; there's no need to modify any of the Simulators.

Ports

Robust uses two main ports:

  • Port 8002 - for services that that are open to the world, mostly because Viewers need to access them. E.g.: the Login service. This port usually can't have firewall restrictions because it's accessed directly from users' computers. (It's possible to use access restrictions only if all of the users are expected to connect from within a certain network.)

  • Port 8003 - for services that are open to the grid's simulators. E.g.: Assets, Inventory. If all of the simulators are known to run within a certain network then it's possible to create firewall rules that restrict access to this port.

Your grid might be using other ports than these. In that case, simply replace every place where we mention one of these ports with the ports that you're actually using.

When a grid uses the Hypergrid it makes the Hypergrid services available on Port 8002, since they need to be accessed by external grids. In many cases the Hypergrid services are wrappers of regular services that run on port 8003. For example, the "real" Assets and Inventory services use Port 8003, but their Hypergrid wrappers use Port 8002.

In order to enable delivery from Kitely Market, you will need to make some Hypergrid services available. But you only want to allow Kitely to access these services. This can be accomplished by running the services on a special port, and using the firewall to allow access to this port only from *.kitely.com. We suggest using the following port:

  • Port 8102 - open only to Kitely (using the firewall). The number "8102" is meant as a reminder that the services that use this port usually use port 8002.

The Helo, Home and Gatekeeper Services

Although we will use Port 8102 for the most sensitive services (Assets, Inventory), there are three Hypergrid services that should use Port 8002: Helo, Home and Gatekeeper. The reason they need to use Port 8002 (or whatever your grid's main port is) is that these services act as identifiers for the grid. In other words, the address "yourgrid.com:8002" is a unique identifier for your grid, and is considered to be a different grid from "yourgrid.com:8102" or "yourgrid.com:1234". If you ever change the port on which these services run then this will change the very identity of your grid. The consequences in Kitely Market will be that your users won't be able to use it anymore since there will be a mismatch between the grid that they used to be in ("yourgrid.com:8102") and the grid that they claim to belong to now ("yourgrid.com:8002"). This may be fixable, so if you ever get into this situation then please contact Kitely. But it's best to avoid this situation, and that's why we recommend that you use your grid's main port (Port 8002) for the Helo, Home and Gatekeeper services.

What are these services? The Helo service is a very small service that just confirms that the server supports Hypergrid. The Home service allows querying the grid's users, which Kitely Market does in order to convert user names to UUID's. The Gatekeeper service is used for teleporting between grids. However, the Gatekeeper service is not actually open! We need the Gatekeeper port to be correct because this address is sent to Kitely and used to identify the grid, but it isn't actually possible to use this address because the Gatekeeper service will not be enabled.

Modify Robust.ini

The following changes assume you're using OpenSim 0.8.0. Kitely Market does support older versions of OpenSim, but in that case there might be small differences in the required configuration; these differences will not be addressed here.

1. Add the following lines at the end of the [ServiceList] section (they were copied from the [ServiceList] section in Robust.HG.ini):

;; Hypergrid UserAgentServerConnector = "8002/OpenSim.Server.Handlers.dll:UserAgentServerConnector" HeloServiceInConnector = "8002/OpenSim.Server.Handlers.dll:HeloServiceInConnector" InstantMessageServerConnector = "8102/OpenSim.Server.Handlers.dll:InstantMessageServerConnector" HGInventoryServiceConnector = "HGInventoryService@8102/OpenSim.Server.Handlers.dll:XInventoryInConnector" HGAssetServiceConnector = "HGAssetService@8102/OpenSim.Server.Handlers.dll:AssetServiceConnector"

Notice that we don't have a line for the Gatekeeper Service. That's what makes it inaccessible.

2. Add the following lines at the end of the [LoginService] section (they were copied from the [LoginService] section in Robust.HG.ini):

;; Hypergrid SRV_HomeURI = "http://127.0.0.1:8002" SRV_InventoryServerURI = "http://127.0.0.1:8102" SRV_AssetServerURI = "http://127.0.0.1:8102" SRV_ProfileServerURI = "http://127.0.0.1:8002" SRV_FriendsServerURI = "http://127.0.0.1:8102" SRV_IMServerURI = "http://127.0.0.1:8102" SRV_GroupsServerURI = "http://127.0.0.1:8102"

Replace every instance of "127.0.0.1" with the address of your grid, e.g. "yourgrid.com".

Notice that the Home service uses port 8002, and most of the other services use port 8102. (The Gatekeeper service doesn't get a mention here.)

If you examined this list with a sharp eye then you may have noticed that the Profile service also uses port 8002, and we haven't mentioned this service before. That's because the Profile service exists in non-Hypergrid versions of OpenSim as well, and the default address for this service uses port 8002. If you're using a different address for your Profile Service then please specify it here. The benefit of specifying the correct profile service is that Kitely Market will be able to show your users' actual pictures, which gives buyers confidence that their products were delivered to the correct avatar. If you're not using a Profile Service then you can leave this setting unchanged; it won't cause any harm.

3. Copy the following sections from Robust.HG.ini to Robust.ini (at the end of the file):

  • [Hypergrid]

  • [GatekeeperService]

  • [UserAgentService]

  • [HGInventoryService]

  • [HGAssetService]

  • [HGInstantMessageService]

Replace every instance of "127.0.0.1" with the address of your grid, e.g. "yourgrid.com".

You may have noticed that the [GateekeeperService] section has some rules regarding who may teleport into the grid. We don't bother to set these rules since the Gatekeeper service isn't actually accessible.

4. Add the following line at the end of the [UserAgentService] section:

ForeignTripsAllowed_Level_0 = false

Configure the Firewall

Set your firewall to allow incoming TCP access to Port 8102 only from *.kitely.com. (If you can't create a wildcard rule then you can allow access from grid.kitely.com instead. This will work for now, but it's not future-proof.)

If you don't have a firewall then you can skip this step. In fact, in that case you can ignore everything regarding Port 8102, and just use Port 8002 in every place that we've mentioned Port 8102.

Testing

After you have configured your grid, test that it now supports Kitely Market. Login to your Kitely account; go to the Shopping Cart; click on the "Grid Manager" link; and add your grid. E.g.: enter "yourgrid.com:8002". You will be asked to Verify your grid: this is a process where Kitely sends a Notecard to your avatar. If the Verification process succeeds then you have successfully configured your grid to support Kitely Market!

If you encounter problems then please contact Kitely at contact@kitely.com.

Tell Your Users

Next, you will want to tell your users how they can use Kitely Market. The basic instructions are these:

  1. Go to Kitely Market ( https://www.kitely.com/market )

  2. Create a Kitely account

  3. Enable the "Export" filter: it's at the bottom-left corner of the Kitely Market page. Only Exportable items can be delivered to other grids.

  4. Browse the market and add items to the Shopping Cart

  5. In the Shopping Cart, select "Deliver to: Other Avatar"

  6. If this is the first time the user is using Kitely Market then they need to add your grid to their list of grids. To do so, click on the Grid Manager and Add the grid: yourgrid.com:8002 (or whatever your grid's address is). If the grid was already added by this user then they can just select it in the drop-down list.

  7. Enter the receiving Avatar name, and click Pay

Your users will not be asked to Verify the grid, because that only needs to be done once and you have already done it.