Teleports

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(Steps)
 
(12 intermediate revisions by one user not shown)
Line 3: Line 3:
 
=Introduction=
 
=Introduction=
  
Teleports in OpenSimulator involve a complex exchange of messages between the simulator hosting the source region, the simulator hosting the destination region (which may be the same simulator that is hosting the source region) and the viewerThis page documents that message exchange.
+
A teleport is the transfer of a user's connection (represented in-world by their avatar) from one location to anotherThese locations can be
  
In terms of basic grid teleports (where all simulators are hosted on the same grid), there are five different scenarios.
+
* Within the same region.
 +
* Between different regions on the same simulator.
 +
* Between different simulators on the same network within the same grid (e.g. a grid hosted on a single network).
 +
* Between different networks within the same grid (e.g. between simulators hosted on OSGrid).
 +
* Between different networks on different grids (i.e. Hypergrid teleport).
  
* Teleport within the same region (intra-region).
+
In OpenSimulator 0.7.5 and for many releases previously, a teleport protocol called SIMULATION/0.1 was used. In OpenSimulator 0.7.6 and after, a teleport protocol called SIMULATION/0.2 is used by default. However, OpenSimulator can still use the SIMULATION/0.1 protocol required by older versions and will automatically inter-operate with them.
* Teleport to an out-of-sight region hosted on the same simulator (same simulator, out-of-sight).
+
* Teleport to an in-sight region hosted on the same simulator (same simulator, in-sight).
+
* Teleport to an out-of-sight region hosted on a different simulator (different simulator, out-of-sight).
+
* Teleport to an in-sight region hosted on a different simulators (different simulator, in-sight).
+
  
These are listed in terms of complexity and hence reliability.  Intra-region teleport is the simplest at all since the avatar just needs to be moved within the region - connections do not need to be torn down and established.
+
If you want to know an eye-watering amount of nitty-gritty about how this works, then please see the [[Teleport Protocol]] page.
  
Same simulator, out-of-sight teleport is the next simplest.  Though the avatar needs to be removed from one scene and placed in another, a second simulator is not involved.  As the regions are out of sight of one another for the client's draw distance, no management of root and child agents is required (see [[Glossary]] for more information on agents).
+
=Configuration=
  
Same simulator, in-sight teleport is similar to out-of-sight teleport except that some management of agents (e.g. downgrade root agent to child on the source region) needs to be done.
+
Normally, no configuration is required. However, from OpenSimulator 0.7.6 onwards, one can force the simulator to always use the older SIMULATION/0.1 protocol to send an avatar to another simulator, receive an avatar from another simulator or both.
  
Different simulator, out-of-sight teleport is similar to same simulator, out-of-sight teleport except that the need to communicate between different simulator processes increases the complexity of the teleport and often introduces a network dependency (unless the simulators are hosted on the same machine).
+
==Using SIMULATION/0.1 to send an avatar to another region==
  
Different simulator, in-sight teleport is the more complex normal grid teleport, since not only is there an interaction between source simulator, destination simulator and viewer, but upgrade and downgrades between child and root agents need to be managed as well.
+
The protocol version used for outgoing teleports is controlled by the MaxOutgoingTransferVersion attribute in the [EntityTransfer] section of OpenSim.ini. Specifying
  
=Same simulator, Out-of-sight, OpenSimulator 0.7.5 =
+
[EntityTransfer]
 +
MaxOutgoingTransferVersion = "SIMULATION/0.1"
  
This is a detailed description of the steps performed for a same simulator, out-of-sight region teleport on OpenSimulator 0.7.5.  This was established with Linden Lab viewer 3.3.4.  Earlier viewers up to LL 1.23 probably have very similar if not identical steps.
+
here will make the simulator use this earlier protocol for outgoing teleports even if the destination has SIMULATION/0.2 available (all such simulators should also have SIMULATION/0.1 available). See OpenSimDefaults.ini for more details.
  
This protocol is known internally as "SIMULATOR/0.1".
+
==Using SIMULATION/0.1 to receive an avatar from another region==
  
The step numbers are just for reference and do not correspond to any labels in the code.
+
In this case, one needs to use the ConnectorProtocolVersion in the [SimulationService] section of StandaloneCommon.ini or GridCommon.ini as appropriate. For example
  
There are three distinct stages; preparing, transferring and cleaning up.
+
[SimulationService]
 +
ConnectorProtocolVersion = "SIMULATION/0.1"
  
==Key==
+
=References=
{| border = "1"
+
! key !! description
+
|-
+
| D  || destination region
+
|-
+
| DCh || neighbour of destination region with child agent
+
|-
+
| G  || grid service
+
|-
+
| S  || source region
+
|-
+
| Sch || neighbour of source region with child agent
+
|-
+
| V  || viewer
+
|}
+
  
==Stage 1: Preparing==
+
* [[Teleport Protocol]] - an extremely in depth look at the teleport protocol.
At this stage, the teleport can be denied (e.g. because destination simulator is full), failed or cancelled without requiring any reversing steps on the source (e.g. reinitializing child agents, etc.)
+
 
+
===Communication===
+
Communication occurs between
+
 
+
* Viewer and source region (V <-> S)
+
* Source region and grid (S -> G)
+
* Source region and destination region (S -> D)
+
 
+
No communication yet occurs between the viewer and the destination region.
+
 
+
===Steps===
+
* P1, V->S, Viewer sends '''TeleportLocationRequest''' UDP packet to its current simulator.  This holds the desired destination region co-ordinates.
+
* P2, Source simulator checks the user is allowed to teleport in principle.
+
* P3, S->G, Source tries to retrieve information about the destination region from the grid service.
+
* P4, Source checks destination is within max teleport distance.  This is because most Second Life compatible viewers cannot teleport further than 4096 regions due to implementation and possibly protocol limitations.
+
* P5, S->D, Source contacts the destination simulator to check whether the agent is allowed to teleport to the destination region.  Failure may occur here because the destination simulator is unavailable, the region is not letting any users in, etc.
+
* P6, S->V, If everything is okay, the viewer is sent a '''TeleportStart''' UDP packet.  This is a very simple packet that just tells the viewer that the teleport is in progress.  At this point on the viewer, the 3D scene will be replaced by a teleport progress screen (classically black with a progress bar in the middle).
+
* P7, Source calculates whether the destination region is in-sight.  In this case, it is out-of-sight.
+
* P8, S->D, Therefore, source asks destination to create an agent in anticipation of a connection from the viewer.  The agent starts as a child agent - it will be upgraded to a root agent on a successful connection.  The session circuit code is passed on so that the destination simulator can recognise a new connection from the viewer.
+
 
+
==Stage 2: Transferring==
+
The teleport is now in flight.  If it fails then cleanup takes significant steps and may not work anyway because the viewer has a different view of what happened - a view which unfortunately could be uncorrectable except by relog).
+
 
+
===Communication===
+
Communication occurs between
+
 
+
* Source region and any neighbouring regions (S -> SCh)
+
* Any neighbouring source region and the viewer (SCh -> V)
+
* Source region to the viewer (S -> V)
+
* Viewer to the destination region (V -> D)
+
* Source region and the destination region (S <-> D)
+
* Destination region to any neighbouring regions (D -> DCh)
+
* Any neighbouring destination regions to the viewer (DCh <-> V)
+
 
+
===Steps===
+
* T1, S->SCh*, If create agent request is successful, source requests closure of existing child agents which were allowing the user to see events in neighbouring and other in-sight regions at the source location. 
+
** T1A, These close requests go from the source simulator to in-sight regions which may be on the same simulator or different simulators.
+
** T1B, SCh*->V, Each close requests triggers a client connection close.  This tears down the client circuit, removes the scene presence (the primary code representation of the agent in the scene) and sends the client a '''DisableSimulator''' event via the Event Queue HTTP capability.
+
* T2, S->V, Source simulator sends an '''EnableSimulator''' Event Queue message for the destination region to the viewer. 
+
** T2A, V->D, This triggers the viewer to send the initial '''UseCircuitCode''' UDP packet to the destination simulator to establish a new connection.
+
* T3, S->V, Very shortly afterwards, the source simulator sends an '''EstablishAgentCommunication''' Event Queue message to the viewer.  This contains the destination simulators HTTP capability root URL. 
+
** T3A, V->D This triggers the viewer to send a '''SEED''' capability request to the destination simulator.  The destination replies with all the capabilities that are available on that simulator.
+
* T4, S->D, Source sends the destination simulator more information about the incoming connection via the '''UpdateAgent''' inter-region communication message.  If the regions are running on the same simulator then the UpdateAgent call waits for the viewer to establish a child connection.  The timeout is 20 seconds.  If the regions are on different simulators then the source simulator is not delayed.
+
* T5, S->V, The source sends the viewer a '''TeleportProgress''' UDP packet.  This is just a status update and advances the viewer's waiting bar for the teleport.
+
* T6, S->V, The source sends the viewer a '''TeleportFinish''' Event Queue message. 
+
* T7, The source now waits 20 seconds for a '''ReleaseAgent''' inter-region message from the destination simulator that the new connection is operational.
+
* T8, V->D, The '''TeleportFinish''' message sent to the viewer triggers it to send a second '''UseCircuitCode''' UDP packet to the destination simulator.  This is largely ignored by OpenSimulator, with the exception that an '''AckPacket''' UDP acknowledgement message is immediately sent back.
+
* T9, V->D, The viewer then sends a '''CompleteAgentMovement''' UDP packet to the destination on the newly established UDP connection.
+
** T9A, This triggers the destination simulator to upgrade the previously established child agent to a full root agent.
+
** T9B, D->S, The destination simulator calls back the source simulator with a '''ReleaseAgent''' inter-region message to tell it that the new connection was successfully established.
+
** T9C, D->DCh*, The destination simulator asks neighbouring regions to initiate child agent connections if appropriate.
+
** T9D, DCh*->V, Each new child agent requests triggers an '''EnableSimulator''' EQ message from the destination child agent region to the viewer.
+
** T9E, V->Dch*, This triggers the viewer to establish a separate connection to each region with an initial '''UseCircuitCode''' UDP message.
+
 
+
==Stage 3: Cleaning up==
+
If stage 2 completes successfully, then all that remains to be done is to clean up the source region.
+
 
+
===Communication===
+
Communication occurs between:
+
 
+
* The source region and the viewer (S <-> V)
+
 
+
===Steps===
+
* C1, Once the source receives the '''ReleaseAgent''' message, it cleans up the old presence by removing the avatar and its attachments from the source scene.  The agent is downgraded from a root agent to a child agent.
+
* C2, S->V, Since the source region is no longer in sight, this child agent is closed completely.  This triggers a '''DisableSimulator''' Event Queue message from the source simulator to the viewer for the old connection.
+
 
+
==General notes==
+
* Once the viewer receives a TeleportStart message from the simulator, the user will be given a cancel option.  Clicking that button sends a TeleportCancel UDP packet from the viewer to the simulator.  If clicked early on in the teleport process, cancellation may succeed.  If clicked later on, there will be various problems (e.g. user is returned to source region but can no longer move).  OpenSimulator does not currently handle cancellation requests very well.
+
* EnableSimulator (step T2) is actually being misused in teleport - it's actually only meant for telling viewers about neighbour regions.  However, it has the side effect of making the agent establish a connection with the destination.  TeleportFinish is enough to get the viewer to establish a UDP connection to the destination simulator (as seen here by the '''UseCircuitCode''' packet that we ignore.  This is more along the lines of the LL teleport process.  This may mean that there's room for considerable simplification in the current OpenSimulator teleport process.
+
 
+
==Failure summary table==
+
 
+
This is a work-in-progress table of what happens if teleport fails at various stages of the process.
+
 
+
{| border="1"
+
! Failure condition !! Viewer symptoms (LL 3.3.4)
+
|-
+
| Source simulator receives the initial TeleportLocationRequest UDP packet from the viewer but does nothing further || Viewer displays a filling progress bar with the message "Requesting Teleport...".  There is no cancel button.  Viewer gives up after 140 seconds and returns the user to their source region where they can act normally.
+
|-
+
| Source simulator replies to the viewer with the TeleportStart UDP packet but does nothing further || Viewer displays a filling progress bar with the message "Requesting Teleport...".  There is a cancel button.  If the cancel button is clicked before the source simulator starts asking the destination simulator to set up agents then cancellation succeeds and the user can act normally.
+
|-
+
| Teleport succeeds up until the point where the viewer tries to setup a connection with the destination simulator in the Transferring stage.  Either destination region cannot be contacted by the viewer or destination region could not reply to viewer (a common cause of this is network issues).  || Source simulator will cancel teleport after a 20 second delay.  In OpenSimulator 0.7.5, things should continue normally and the viewer able to see/cross into neighbours from the source region, do other teleports and even perform the same teleport later on if the destination region network issues are resolved.  Before 0.7.5 there may be problems with this process.
+
|-
+
| Teleport succeeds up until the point where the viewer tries to complete movement (with the CompleteAgentMovement packet) into the destination region.  The region either does not receive this (and for some reason the viewer doesn't detect that is should retry) or completely fails to act on it.  Therefore, the source region does not receive the receive the ReleaseAgent message from the destination region.  || Source simulator will cancel teleport after a 20 second delay.  In OpenSimulator 0.7.5, things should continue normally and the viewer able to see/cross into neighbours from the source region, do other teleports and even perform the same teleport later on if the destination region network issues are resolved.  Before 0.7.5 there may be problems with this process.
+
|-
+
| Teleport succeeds except that the final ReleaseAgent signal from the destination to the source does not occur.  One possible cause is network issues - this is the first point at which the destination region has to contact the source region directly. || Source simulator will cancel teleport after a 20 second delay.  However, as the viewer has successfully teleported to the destination (as far as its concerned), this leaves the viewer session in an unuseable state (avatar cannot move, teleport, etc.).  This is currently the behaviour in OpenSimulator 0.7.5.  Unfortunately, it's practically impossible to distinguish between this case and the preceedng one.
+
|}
+
 
+
==Example log==
+
 
+
For reference, these are the relevant log entries taken from a successful teleport of Justin Clark-Casey from a region called "test one" to a region called "test two".  This was taken with
+
 
+
* Packets logged (via the "debug packet 1" command on the console)
+
* Inbound and outbound non-poll events logged (via the "debug http all 6" console command). 
+
* Event queue messages logged (via the "debug eq 1" command on the console.
+
 
+
The OpenSimulator commit was 3ac6a423 (post 0.7.4).  The exact messages displayed will almost certainly change in the future.
+
 
+
<pre style="white-space: pre-wrap;
+
white-space: -moz-pre-wrap;
+
white-space: -pre-wrap;
+
white-space: -o-pre-wrap;
+
word-wrap: break-word">
+
00:50:41 - [CLIENT]: PACKET IN  from Justin Clark-Casey (root ) in test one - TeleportLocationRequest
+
00:50:41 - [ENTITY TRANSFER MODULE]: Teleporting Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from test one to http://192.168.1.2:9000/ (http://192.168.1.2:9000/) test two/<127.6335, 140.0397, 25.1643>
+
00:50:41 - [ENTITY TRANSFER MODULE]: Destination is running version SIMULATION/0.1
+
00:50:41 - [CLIENT]: PACKET OUT to  Justin Clark-Casey (root ) in test one - TeleportStart
+
00:50:41 - [SCENE]: Region test two told of incoming child agent Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 (circuit code 1017396278, IP 192.168.1.2, viewer Second Life Release 3.3.4.262321, teleportflags (ViaLocation), position <127.6335, 140.0397, 25.1643>)
+
00:50:41 - [WEB UTIL]: HTTP OUT 30 SynchronousRestForms POST http://localhost:8003/presence
+
00:50:41 - [WEB UTIL]: HTTP OUT 30 took 3ms, 1ms writing
+
00:50:41 - [SCENE]: Region test two authenticated and authorized incoming child agent Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 (circuit code 1017396278)
+
00:50:41 - [CAPS]: Registered seed capability /CAPS/a358dd6d-5d39-407e-a29a-7b8b59d763010000/ for e4f3924a-5a7c-4e1a-bee7-aa96580f2515
+
00:50:41 - [SCENE PRESENCE]: Closing child agents. Checking 1 regions in test one
+
00:50:41 - POLLED FOR EQ MESSAGES BY e4f3924a-5a7c-4e1a-bee7-aa96580f2515 in test one
+
00:50:41 - Eq OUT EnableSimulator                to Justin Clark-Casey  test one
+
00:50:41 - [LLUDPSERVER]: Handling UseCircuitCode request for circuit 1017396278 to test two from IP 192.168.1.2:55326
+
00:50:41 - [SCENE]: Adding new child scene presence Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 to scene test two at pos <127.6335, 140.0397, 25.1643>
+
00:50:41 - [ENTITY TRANSFER MODULE]: Set release callback URL to http://192.168.1.2:9000/agent/e4f3924a-5a7c-4e1a-bee7-aa96580f2515/11111111-bf88-45ac-aace-35bd76426c81/release/ in test one
+
00:50:41 - [SCENE]: Incoming child agent update for e4f3924a-5a7c-4e1a-bee7-aa96580f2515 in test two
+
00:50:41 - [CLIENT]: PACKET OUT to  Justin Clark-Casey (root ) in test one - TeleportProgress
+
00:50:41 - [ENTITY TRANSFER MODULE]: Sending new CAPS seed url http://192.168.1.2:9000/CAPS/a358dd6d-5d39-407e-a29a-7b8b59d763010000/ from test one to Justin Clark-Casey
+
00:50:42 - POLLED FOR EQ MESSAGES BY e4f3924a-5a7c-4e1a-bee7-aa96580f2515 in test one
+
00:50:42 - Eq OUT EstablishAgentCommunication    to Justin Clark-Casey  test one
+
00:50:42 - Eq OUT TeleportFinish                to Justin Clark-Casey  test one
+
00:50:42 - [LLUDPSERVER]: Handling UseCircuitCode request for circuit 1017396278 to test two from IP 192.168.1.2:55326
+
00:50:42 - [SCENE PRESENCE]: Completing movement of Justin Clark-Casey into region test two in position <127.6335, 140.0397, 25.1643>
+
00:50:42 - [SCENE]: Upgrading child to root agent for Justin Clark-Casey in test two
+
00:50:42 - [WEB UTIL]: HTTP OUT 31 SynchronousRestForms POST http://localhost:8003/friends
+
00:50:42 - [WEB UTIL]: HTTP OUT 31 took 2ms, 0ms writing
+
00:50:42 - [WEB UTIL]: HTTP OUT 32 SynchronousRestForms POST http://localhost:8003/presence
+
00:50:42 - [BASE HTTP SERVER]: HTTP IN 27 :9000 stream handler POST /CAPS/a358dd6d-5d39-407e-a29a-7b8b59d763010000/ SEED  from 192.168.1.2:47107
+
00:50:42 - [BASE HTTP SERVER]: <llsd><array><string>AttachmentResources</string><string>AvatarPickerSearch</string><string>ChatSessionRequest</string><string>CopyInventoryFromNotecard</string><string>CreateInventoryCategory</string><string>DispatchRegionInfo</string><string>EstateChangeInfo</string><string>EventQueueGet</string><string>EnvironmentSettings</string><string>ObjectMedia</string><string>ObjectMediaNavigate</string><string>FetchLib2</string><string>FetchLibDescendents2</string><string>FetchInventory2</string><string>FetchInventoryDescendents2</string><string>GetDisplayNames</string><string>GetTexture</string><string>GetMesh</string><string>GetObjectCost</string><string>GetObjectPhysicsData</string><string>GroupProposalBallot</string><string>HomeLocation</string><string>LandResources</string><string>MapLayer</string><string>MapLayerGod</string><string>MeshUploadFlag</string><string>NewFileAgentInventory</string><string>ParcelPropertiesUpdate</string><string>ParcelMediaURLFilterList</string><string>ParcelNavigateMedia</string><string>ParcelVoiceInfoRequest</string><string>ProductInfoRequest</string><string>ProvisionVoiceAccountRequest</string><string>RemoteParcelRequest</string><string>RequestTextureDownload</string><string>ResourceCostSelected</string><string>SearchStatRequest</string><string>SearchStatTracking</string><string>SendPostcard</string><string>SendUserReport</string><string>SendUserReportWithScreenshot</string><string>ServerReleaseNotes</string><string>SimConsole</string><string>SimulatorFeatures</string><string>SetDisplayName</string><string>SimConsoleAsync</string><string>StartGroupProposal</string><string>TextureStats</string><string>UntrustedSimulatorMessage</string><string>UpdateAgentInformation</string><string>UpdateAgentLanguage</string><string>UpdateGestureAgentInventory</string><string>UpdateNotecardAgentInventory</string><string>UpdateScriptAgent</string><string>UpdateGestureTaskInventory</string><string>UpdateNotecardTaskInventory</string><string>UpdateScriptTask</string><string>UploadBakedTexture</string><string>ViewerMetrics</string><string>ViewerStartAuction</string><string>ViewerStats</string></array></llsd>\n...
+
00:50:42 - [CAPS]: Received SEED caps request in test two for agent e4f3924a-5a7c-4e1a-bee7-aa96580f2515
+
00:50:42 - [BASE HTTP SERVER]: HTTP IN 27 :9000 took 7ms
+
00:50:42 - [BASE HTTP SERVER]: HTTP IN 29 :9000 stream handler GET /CAPS/583eb413-3130-418c-b344-38e618bd22d7 SimulatorFeatures e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from 192.168.1.2:47110
+
00:50:42 - [BASE HTTP SERVER]: ...
+
00:50:42 - [BASE HTTP SERVER]: HTTP IN 29 :9000 took 0ms
+
00:50:42 - [WEB UTIL]: HTTP OUT 32 took 134ms, 2ms writing
+
00:50:42 - [WEB UTIL]: HTTP OUT 33 SynchronousRestForms POST http://localhost:8003/griduser
+
00:50:42 - [WEB UTIL]: HTTP OUT 33 took 88ms, 2ms writing
+
00:50:42 - [SCENE PRESENCE]: Releasing Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 with callback to http://192.168.1.2:9000/agent/e4f3924a-5a7c-4e1a-bee7-aa96580f2515/11111111-bf88-45ac-aace-35bd76426c81/release/
+
00:50:42 - POLLED FOR EQ MESSAGES BY e4f3924a-5a7c-4e1a-bee7-aa96580f2515 in test two
+
00:50:42 - Eq OUT AgentGroupDataUpdate          to Justin Clark-Casey  test two
+
00:50:42 - Eq OUT AgentGroupDataUpdate          to Justin Clark-Casey  test two
+
00:50:42 - Eq OUT AvatarGroupsReply              to Justin Clark-Casey  test two
+
00:50:42 - Eq OUT ParcelProperties              to Justin Clark-Casey  test two
+
00:50:42 - [SCENE PRESENCE]: baked textures are in the cache for Justin Clark-Casey
+
00:50:42 - [WEB UTIL]: HTTP OUT 34 SynchronousRestForms POST http://localhost:8003/grid
+
00:50:42 - [WEB UTIL]: HTTP OUT 34 took 8ms, 1ms writing
+
00:50:42 - [BASE HTTP SERVER]: HTTP IN 30 :9000 stream handler GET /CAPS/0020/9b7f736f-dfd1-42f3-b200-8bd0e8dbfd2d EnvironmentSettings e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from 192.168.1.2:47114
+
00:50:42 - [BASE HTTP SERVER]: ...
+
00:50:42 - [BASE HTTP SERVER]: HTTP IN 30 :9000 took 3ms
+
00:50:42 - [CLIENT]: PACKET OUT to  Justin Clark-Casey (child) in test one - KillObject
+
00:50:42 - [SCENE PRESENCE]: Making Justin Clark-Casey a child agent in test one
+
00:50:44 - [CLIENT]: Close has been called for Justin Clark-Casey attached to scene test one
+
00:50:44 - [SCENE]: Removing child agent Justin Clark-Casey e4f3924a-5a7c-4e1a-bee7-aa96580f2515 from test one
+
00:50:45 - POLLED FOR EQ MESSAGES BY e4f3924a-5a7c-4e1a-bee7-aa96580f2515 in test one
+
00:50:45 - Eq OUT DisableSimulator              to Justin Clark-Casey  test one
+
00:50:45 - [ENTITY TRANSFER STATE MACHINE]: Agent e4f3924a-5a7c-4e1a-bee7-aa96580f2515 cleared from transit in test one
+
</pre>
+
 
+
=Same simulator, Out-of-sight, OpenSimulator Development Code (will be 0.7.6). =
+
 
+
This is a detailed description of the steps performed for a same simulator, out-of-sight region teleport on current development code.  The protocol has changed sThis was established with Linden Lab viewer 3.3.4.  Earlier viewers up to LL 1.23 probably have very similar if not identical steps.
+
 
+
This protocol is known internally as "SIMULATOR/0.2".  The next OpenSimulator release which incorporates this updated protocol will still be backwards-compatible with older simulators that only implement "SIMULATOR/0.1" (i.e. they can both receive and send users to these older simulators).
+
 
+
'''NOTE: This section is very much a work in progress.  Large parts are copied and pasted from the SIMULATOR/0.1 description above and so will NOT be accurate.'''
+
 
+
The step numbers are just for reference and do not correspond to any labels in the code.
+
 
+
There are three distinct stages; preparing, transferring and cleaning up.
+
 
+
==Key==
+
{| border = "1"
+
! key !! description
+
|-
+
| D  || destination region
+
|-
+
| DCh || neighbour of destination region with child agent
+
|-
+
| G  || grid service
+
|-
+
| S  || source region
+
|-
+
| Sch || neighbour of source region with child agent
+
|-
+
| V  || viewer
+
|}
+
 
+
==Stage 1: Preparing==
+
At this stage, the teleport can be denied (e.g. because destination simulator is full), failed or cancelled without requiring any reversing steps on the source (e.g. reinitializing child agents, etc.)
+
 
+
===Communication===
+
Communication occurs between
+
 
+
* Viewer and source region (V <-> S)
+
* Source region and grid (S -> G)
+
* Source region and destination region (S -> D)
+
 
+
No communication yet occurs between the viewer and the destination region.
+
 
+
===Steps===
+
* P1, V->S, Viewer sends '''TeleportLocationRequest''' UDP packet to its current simulator.  This holds the desired destination region co-ordinates.
+
* P2, S, Source simulator checks the user is allowed to teleport in principle.
+
* P3, S->G, Source tries to retrieve information about the destination region from the grid service.
+
* P4, S, Source checks destination is within max teleport distance.  This is because most Second Life compatible viewers cannot teleport further than 4096 regions due to implementation and possibly protocol limitations.
+
* P5, S->D, Source contacts the destination simulator to check whether the agent is allowed to teleport to the destination region.  Failure may occur here because the destination simulator is unavailable, the region is not letting any users in, etc.
+
* P6, S->V, If everything is okay, the viewer is sent a '''TeleportStart''' UDP packet.  This is a very simple packet that just tells the viewer that the teleport is in progress.  At this point on the viewer, the 3D scene will be replaced by a teleport progress screen (classically black with a progress bar in the middle).
+
* P7, S, Source calculates whether the destination region is in-sight.  In this case, it is out-of-sight.
+
* P8, S->D, Therefore, source asks destination to create an agent in anticipation of a connection from the viewer.  The agent starts as a child agent - it will be upgraded to a root agent on a successful connection by the viewer.  The session circuit code is passed on so that the destination simulator can recognise a new connection from the viewer.
+
 
+
==Stage 2: Transferring==
+
The teleport is now in flight.  If it fails then cleanup takes significant steps and may not work anyway because the viewer has a different view of what happened - a view which unfortunately could be uncorrectable except by relog).
+
 
+
===Communication===
+
Communication occurs between
+
 
+
* Source region and any neighbouring regions (S -> SCh)
+
* Any neighbouring source region and the viewer (SCh -> V)
+
* Source region to the viewer (S -> V)
+
* Viewer to the destination region (V -> D)
+
* Source region and the destination region (S <-> D)
+
* Destination region to any neighbouring regions (D -> DCh)
+
* Any neighbouring destination regions to the viewer (DCh <-> V)
+
 
+
===Steps===
+
* T1, S->V, The source sends the viewer a '''TeleportFinish''' Event Queue message.  This contains information about the destination simulator's IP:Port and it's capabilities URL.
+
** T1A, V->D, The '''TeleportFinish''' message sent to the viewer triggers it to send a ''UseCircuitCode''' UDP packet to the destination simulator in order to establish the connection.
+
** T1B, D->V, The viewer creates the connection and sends back a PacketAckPacket back to the viewer.
+
** T1C, V->D, This viewer also sends a '''SEED''' capability request to the destination simulator.  The destination replies with all the capabilities that are available on that simulator.
+
* T2, V->D, The viewer then sends a '''CompleteAgentMovement''' UDP packet to the destination on the newly established UDP connection.
+
* T2A, D, The connection then waits on the destination simulator until the source simulator has sent an UpdateAgent message.  It does this by polling ScenePresence.m_originRegionID, which should only be set once an UpdateAgent has been received by the destination.  It will wait for 4 seconds.  ('''TODO: Check if there is an issue here where a previously root agent may have become a child agent before becoming a root agent again on teleport''').
+
* T3, S->D, Meanwhile. the source sends the destination more information about the incoming connection via the '''UpdateAgent''' inter-region communication message.  If the regions are running on the same simulator then the UpdateAgent call waits for the viewer to establish a root connection.  The timeout is 20 seconds.  If the regions are on different simulators then the source simulator is not delayed.
+
* T3A, D, The destination processes the '''UpdateAgent''' and sets ScenePresence.m_originRegionID.  It then waits for the paused connection thread to upgrade the child agent to a root agent.
+
* T4, D, The connection thread upgrades the previously child agent to a root agent.
+
* T4A, D->V, The connection thread sends the '''AgentMovementComplete''' UDP message back to the viewer.
+
* T4B, D->V, The connection thread sends appearance and information on other avatars back to the viewer.
+
* T4C, D->DCh*, The connection thread asks applicable neighbouring regions to initiate child agent connections.
+
* T4D, DCh, If a destination child region already has a child agent, then it signals that this should not be closed by the source region via the ScenePresence.DoNotCloseAfterTeleport flag (for situations where teleport is between neighbouring regions or regions that are only separated by one active region.
+
 
+
==Stage 3: Cleaning up==
+
If stage 2 completes successfully, then all that remains to be done is to clean up the source region.
+
 
+
===Communication===
+
Communication occurs between:
+
 
+
* The source region to source child regions (S -> SCh*)
+
 
+
===Steps===
+
* C1, S, Meanwhile, the source region pauses (currently 15 secs) before possibly closing the old connection.  An earlier close can cause a viewer crash or place the avatar at an infinite position for a few seconds.
+
* C1A, S, However, if the ScenePresence.DoNotCloseAfterTeleport flag has been set, we do not close the connection.  This may have been set if the user immediately teleported back into a region which neighbours the original source region (and hence should retain the child connection).
+
* C1B, S->SCh*, If the ScenePresence.DoNotCloseAfterTeleport flag has not been set, send '''CloseAgent''' messages to child regions to close their connections.  '''TODO: This may be a bug where we end up closing other child connections that should not close, for the same regions as given previously.  Possibly could resolve this by checking and resetting ScenePresence.DoNotCloseAfterTeleport in Scene.RemoveClient() instead the acd lock.  On furhter investigation, not possible since RemoveClient occurs well within LLClientView.Close().  May need to restructure code.''')
+
 
+
==General notes==
+
* Once the viewer receives a TeleportStart message from the simulator, the user will be given a cancel option.  Clicking that button sends a TeleportCancel UDP packet from the viewer to the simulator.  If clicked early on in the teleport process, cancellation may succeed.  If clicked later on, there will be various problems (e.g. user is returned to source region but can no longer move).  OpenSimulator does not currently handle cancellation requests very well.
+
 
+
==Failure summary table==
+
 
+
This is a work-in-progress table of what happens if teleport fails at various stages of the process.
+
 
+
'''Not yet properly applicable to V2'''
+
 
+
{| border="1"
+
! Failure condition !! Viewer symptoms (LL 3.3.4)
+
|-
+
| Source simulator receives the initial TeleportLocationRequest UDP packet from the viewer but does nothing further || Viewer displays a filling progress bar with the message "Requesting Teleport...".  There is no cancel button.  Viewer gives up after 140 seconds and returns the user to their source region where they can act normally.
+
|-
+
| Source simulator replies to the viewer with the TeleportStart UDP packet but does nothing further || Viewer displays a filling progress bar with the message "Requesting Teleport...".  There is a cancel button.  If the cancel button is clicked before the source simulator starts asking the destination simulator to set up agents then cancellation succeeds and the user can act normally.
+
|-
+
| Teleport succeeds up until the point where the viewer tries to setup a connection with the destination simulator in the Transferring stage.  Either destination region cannot be contacted by the viewer or destination region could not reply to viewer (a common cause of this is network issues).  || Source simulator will cancel teleport after a 20 second delay.  In OpenSimulator 0.7.5, things should continue normally and the viewer able to see/cross into neighbours from the source region, do other teleports and even perform the same teleport later on if the destination region network issues are resolved.  Before 0.7.5 there may be problems with this process.
+
|-
+
| Teleport succeeds up until the point where the viewer tries to complete movement (with the CompleteAgentMovement packet) into the destination region.  The region either does not receive this (and for some reason the viewer doesn't detect that is should retry) or completely fails to act on it.  Therefore, the source region does not receive the receive the ReleaseAgent message from the destination region.  || Source simulator will cancel teleport after a 20 second delay.  In OpenSimulator 0.7.5, things should continue normally and the viewer able to see/cross into neighbours from the source region, do other teleports and even perform the same teleport later on if the destination region network issues are resolved.  Before 0.7.5 there may be problems with this process.
+
|-
+
| Teleport succeeds except that the final ReleaseAgent signal from the destination to the source does not occur.  One possible cause is network issues - this is the first point at which the destination region has to contact the source region directly. || Source simulator will cancel teleport after a 20 second delay.  However, as the viewer has successfully teleported to the destination (as far as its concerned), this leaves the viewer session in an unuseable state (avatar cannot move, teleport, etc.).  This is currently the behaviour in OpenSimulator 0.7.5.  Unfortunately, it's practically impossible to distinguish between this case and the preceedng one.
+
|}
+
 
+
= Legacy documentation =
+
 
+
This documentation is legacy because in part it refers to components and mechanisms that have since been changed.  Chiefly, grid services are now discrete services hosted by a standalone or in one or more ROBUST instances - the discrete user, inventory, etc. servers no longer exist.  Also inventory is no longer fully loaded onto a simulator when a root agent arrives there - instead it is pulled from the grid inventory service on-demand.
+
 
+
== Grid Teleport Procedure ==
+
 
+
[[Image:GridTeleports.jpg|500px]]
+
 
+
== Hypergrid Teleport Procedure ==
+
 
+
[[Image:HypergridTeleports.jpg|500px]]
+
 
+
== Open Grid Protocol Teleport Procedure ==
+
 
+
See [http://wiki.secondlife.com/wiki/OGP_Explained#Teleport OGP Explained "Teleport"]
+
 
+
== Related ==
+
 
+
[[Image:Child-event-queue.png|500px]]
+
 
+
== Teleports in OpenSimulator as of 2009-02-06 ==
+
 
+
[[Image:Teleport.jpg]]
+
 
+
== Teleport Study (2009-03-05) ==
+
 
+
The following four pictures compare the current agent transfer scheme with 3 possible agent transfer schemes. The different schemes have slightly different requirements with respect to authentication.
+
 
+
[[Image:TPCurrent.JPG]]
+
 
+
[[Image:TPScenarioA.JPG]]
+
 
+
[[Image:TPScenarioB.JPG]]
+
 
+
[[Image:TPScenarioC.JPG]]
+

Latest revision as of 16:43, 22 October 2013

Contents

[edit] Introduction

A teleport is the transfer of a user's connection (represented in-world by their avatar) from one location to another. These locations can be

  • Within the same region.
  • Between different regions on the same simulator.
  • Between different simulators on the same network within the same grid (e.g. a grid hosted on a single network).
  • Between different networks within the same grid (e.g. between simulators hosted on OSGrid).
  • Between different networks on different grids (i.e. Hypergrid teleport).

In OpenSimulator 0.7.5 and for many releases previously, a teleport protocol called SIMULATION/0.1 was used. In OpenSimulator 0.7.6 and after, a teleport protocol called SIMULATION/0.2 is used by default. However, OpenSimulator can still use the SIMULATION/0.1 protocol required by older versions and will automatically inter-operate with them.

If you want to know an eye-watering amount of nitty-gritty about how this works, then please see the Teleport Protocol page.

[edit] Configuration

Normally, no configuration is required. However, from OpenSimulator 0.7.6 onwards, one can force the simulator to always use the older SIMULATION/0.1 protocol to send an avatar to another simulator, receive an avatar from another simulator or both.

[edit] Using SIMULATION/0.1 to send an avatar to another region

The protocol version used for outgoing teleports is controlled by the MaxOutgoingTransferVersion attribute in the [EntityTransfer] section of OpenSim.ini. Specifying

[EntityTransfer]
MaxOutgoingTransferVersion = "SIMULATION/0.1" 

here will make the simulator use this earlier protocol for outgoing teleports even if the destination has SIMULATION/0.2 available (all such simulators should also have SIMULATION/0.1 available). See OpenSimDefaults.ini for more details.

[edit] Using SIMULATION/0.1 to receive an avatar from another region

In this case, one needs to use the ConnectorProtocolVersion in the [SimulationService] section of StandaloneCommon.ini or GridCommon.ini as appropriate. For example

[SimulationService]
ConnectorProtocolVersion = "SIMULATION/0.1"

[edit] References

Personal tools
General
About This Wiki