Revision as of 12:45, 13 October 2014

Introduction

In the vast majority of cases, viewer requests are handled by the simulator which then interacts with backend services (asset, inventory, etc.) as appropriate.

However, in the default configuration some of these requests are handled by the viewer interacting with a backend service directly. For instance, on login, the login service passes the viewer a map URL as configured in the MapTileURL section of [LoginService] in Robust.ini. When the viewer requires tiles to display on the main map, it contacts this URL to fetch them. The URL itself is served by the ROBUST service on the public grid port (8002 by default).

There is also experimental scope to handle more requests directly. However, the only experimental example is one to handle GetTexture requests directly from a service rather than via a simulator.

Direct GetTexture capability handling

GetTexture is a client-viewer protocol capability by which clients (viewers) can request textures via HTTP instead of the old UDP based mechanisms.

Normally, OpenSimulator handles this by providing a capability endpoint that resolves to the simulator occuped by the user's avatar. Requests are received by the simulator and the asset retrieved from cache or by a call to the backend asset service as appropriate.

However, we can also configure GetTexture to be handled directly by a service instead via the public grid port. The capability endpoint passed to the viewer then resolves directly to this service instead of the simulator, much like map tiles are provided directly by a service.

Configuration

The first thing to do is to configure the service to provide the GetTexture capability connector. We can do this with the config below.

[Startup]
 
[ServiceList]
GetTextureConnector = "8010/OpenSim.Capabilities.Handlers.dll:GetTextureServerConnector"
 
[Network]
port = 8010
 
[CapsService]
AssetService = "OpenSim.Services.AssetService.dll:AssetService"
 
[DatabaseService]
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=opensim;User ID=opensim;Password=mypassword;Old Guids=true;"
 
[AssetService]

I'm assuming here that we are running the GetTexture service inside an entirely separate Robust service instance. However, it can be run in a Robust shell that it also handling other services (e.g. the default grid one that handles all services). In thie case, you can leave some sections out as we shall outline below.

Here is an explanation of each section.

• [Startup] - This is blank and only here to because the Robust service shell currently mandates it. It may not be necessary in the future. In a shared service shell an existing [Startup] section will be used.
• [ServiceList] - This triggers the initialization of the GetTexture capability connector. Here, we explicitly specify a port of 8010 though this can be omitted if it is the same as the default 'port' setting in the Network section. This is the port by which the viewer will be communicating with the GetTextureConnector so it must be accessible to a viewer through your firewall. You should not be running any private services (e.g. internal asset service) on this port.
• [Network].port - OpenSimulator will currently always complain if this is not present even if you only have one connector and that explicitly specifies the port you are using (as above). If you are expicitly specifying the GetTextureConnector port then this can be any free port on your server (it will not be used if there are no other services). If you are running GetTextureConnector in a shared service shell then any existing port setting will suffice.
• [CapsService].AssetService - This specifies the asset service for GetTextureConnector to initialize from which to fetch textures (which are assets).
• [DatabaseService] - This contains the settings for the AssetService to access the database. If GetTextureConnector is sharing the robust shell with other services then this very probably already exists.
• [AssetService] - This section is blank and exists only to stop AssetService fatally complaining. It may disappear as a requirement in the future.

Now, when you startup the Robust shell hosting GetTextureConnector and run the command "show http-handlers" you should see something like the following (for clarity we show the output where GetTextureConnector is the only thing running in the shell).

R.O.B.U.S.T.# show http-handlers
Registered HTTP Handlers for server at 0.0.0.0:8010
* XMLRPC:
* HTTP:
* HTTP (poll):
* JSONRPC:
* LLSD:
* StreamHandlers (1):
  GET:/CAPS/GetTexture/

This shows that the endpoint /CAPS/GetTexture is now available.

Now we need to configure the simulators to provide viewers with the GetTexture capability that points to the service. In the [ClientStack.LindenCaps] section of OpenSim.ini for each simulator we need to add something like the following.

[ClientStack.LindenCaps]
    Cap_GetTexture = "http://192.168.1.2:8010/CAPS/GetTexture/"

This overrides the usual "localhost" setting specified in bin/OpenSimDefaults.ini. In thie case, the URL points to a LAN IP (192.168.1.2). But for a public grid, this needs to be a public host that can be reached by all viewers (e.g. services.mygrid.com).

Now, when a viewer logs in it will make GetTexture requests directly to the service, by passing the simulator entirely. If the GetTextureConnnector is running in its own shell, you can check this is happening by running a command such as "show stats httpserver.8010.HttpRequestsServed.

R.O.B.U.S.T.# show stats httpserver.8010.HTTPRequestsServed
httpserver.8010.HTTPRequestsServed : 139 requests, 0 requests/s, 0 requests/s

In this case, we can see that the service has now served 139 requests. Unfortunately, it's harder to check if the shell is being shared by multiple services on the same port - we do not currently register stats to show capabilities (though this should change in the future).