SimulatorLoginProtocol

(This page is a work in progress)

Process
There are 4 basic steps to the viewer login process.

Step 1
The viewer contacts the grid login service. On a viewer, this can be specified by the -loginuri command line switch or by picking a grid in the grid manager of a viewer that provides this.

The viewer sends an XMLRPC login_to_simulator message to the loginuri. This provides


 * "first" - User first name
 * "last" - User last name
 * "passwd" - Hashed password
 * "version" - Viewer version
 * "start" - Start location. If "home" then the user's home location, "last" is the user's location on previous logout.  Start can also be a named region and location (see data section below for more information on this).

Step 2
If the user is authenticated, the simulator at which they want to start is contacted and told that they are coming. It is passed a circuit code for that viewer.

Step 3
If the simulator will accept the user, then the user is passed the details of this simulator (chiefly the URI to use, as well as the circuit code).

Step 4
The viewer connects directly to the simulator and is authenticated using the circuit code.

Example XML-RPC Call
The simulator exposes an XML-RPC method called login_to_simulator at the loginuri URL. This takes a number of parameters from the viewer. Here's an example call.



XML-RPC Call Parameters
Required Parameters


 * first - First name of the user.
 * last - Last name of the user.
 * passwd - MD5 hash of the user's password with the string "$1$" prepended.
 * start - The region in which the user should start upon login. This is one of
 * "home" - start in the user's home location
 * "last" - start in the location from which the user last logged out
 * A specific location. This is in the format "uri:&amp;&amp;&amp;".  For instance, the string "uri:test&amp;128&amp;128&amp;0" above signals that the user should login to the center of the region named test (the avatar is placed on the ground if given a z-coordinate below terrain).
 * channel - Name of the viewer/client connecting.
 * version - Version number of the viewer/client connecting.
 * platform - (Lin,Mac,Win). Currently ignored by OpenSimulator.
 * platform_string - The operating system description/version (e.g. 'Linux 5.8', 'Fedora 32', etc)
 * platform_version
 * mac - MAC address of the network card used by the client/viewer to make the connection.
 * id0 - A hardware hash based on the serial number of user's first hard drive. Used by Second Life to uniquely identify computers and track users. Currently unused by OpenSimulator.
 * agree_to_tos - Boolean (true|false). Has user agreed to terms of service on Second Life. Currently unused by OpenSimulator.
 * read_critical - Boolean (true|false). Has user read terms of service and other or other docs on Second Life. Currently unused by OpenSimulator.
 * viewer_digest - MD5 hash of the viewer executable. Currently unused by OpenSimulator.
 * address_size
 * extended_errors
 * last_exec_event - An integer. Function unknown.  Currently unused by OpenSimulator.
 * last_exec_duration
 * skipoptional - Boolean (true|false). Skip options?  Currently unused by OpenSimulator.
 * options - A list of strings. Function unknown, probably used to control data sent back by the login service. Currently unused by OpenSimulator which sends back all data every time.

Option Parameters (currently unused by OpenSimulator)


 * adult_compliant
 * advanced_mode
 * avatar_picker_url
 * buddy-list
 * classified_categories
 * currency
 * destination_guide_url
 * display_names
 * event_categories
 * event_notifications
 * gestures
 * global-textures
 * inventory-root
 * inventory-skeleton
 * inventory-lib-root
 * inventory-lib-owner
 * inventory-skel-lib
 * login-flags
 * max-agent-groups
 * max_groups
 * map-server-url
 * newuser-config
 * search
 * tutorial_setting
 * ui-config
 * voice-config

For more documentation on the option parameters see the |Optional Responses in the Second Life wiki

Example XML-RPC Response
Here's an example response to the example call above. If you are looking to use this information in code, I recommend that you start by using only the parameters that you actually need. There are likely many parameters here that are historical and actually no longer or never used by viewers (and which one day should be cleaned up).

login-flags message Welcome, Avatar! inventory-lib-root first_name Justin ui-config event_categories seconds_since_epoch 1411075065 inventory-skeleton sim_ip 192.168.1.2            map-server-url http://192.168.1.2:8002/ buddy-list gestures initial-outfit inventory-skel-lib session_id 6ac2e761-f490-4122-bf6c-7ad8fbb17002 region_size_x 256 region_size_y 256 agent_id f2f493c0-27d3-4cf2-be97-b44dfdad13b6 event_notifications login true agent_access M            secure_session_id fe210274-9056-467a-aff7-d95f60bacccc last_name Clark-Casey 

XML-RPC Response Parameters
The parameters are as follows:

AddClassifiedCategory((Int32) 1, "Shopping"); AddClassifiedCategory((Int32) 2, "Land Rental"); AddClassifiedCategory((Int32) 3, "Property Rental"); AddClassifiedCategory((Int32) 4, "Special Attraction"); AddClassifiedCategory((Int32) 5, "New Products"); AddClassifiedCategory((Int32) 6, "Employment"); AddClassifiedCategory((Int32) 7, "Wanted"); AddClassifiedCategory((Int32) 8, "Service"); AddClassifiedCategory((Int32) 9, "Personal"); but usefulness is unknown.
 * home - The home location of the user.  This is in the format "{'region_handle':[r,r], 'position':[r,r,r<z-region-coord>], 'look_at':[r<x-coord>,r<y-coord>,r<z-coord>]}.  For example "{'region_handle':[r256000,r256000], 'position':[r50,r100,r200], 'look_at':[r1,r0,r0]}".
 * region_handle gives the grid-coordinates in meters. So for a region located that the 1000,1000 co-ordinate on the map, this is 256000, 256000.
 * position is the position in the region.
 * look_at is the direction the avatar should be facing. This is a unit vector so (0, 1, 0) is facing straight north, (1, 0, 0) is east, (0,-1, 0) is south and (-1, 0, 0) is west.
 * look_at - The direction in which the avatar should be facing upon login. This is a unit vector so (0, 1, 0) is facing straight north, (1, 0, 0) is east, (0,-1, 0) is south and (-1, 0, 0) is west.
 * agent_access - The current maturity access level of the user. OpenSimulator currently always sets this to "M" (probably mature).  Probably unused.
 * agent_access_max - The maximum level of region that user can access. OpenSimulator currently always sets this to "A" (probably adult).  Probably unused.
 * seed_capability - The URL that the viewer should use to request further capabilities.
 * first_name - First name of this user.
 * last_name - Last name of this user.
 * agent_id - The ID of this user.
 * sim_ip - The IP to use to communicate with the receiving simulator.
 * sim_port - The UDP port to use to communicate with the receiving simulator.
 * http_port - Function unknown. OpenSimulator currently always sets this to 0.  The port given directly for capabilities is used instead.
 * start_location - The parameter given in the start parameter in the login request ("last", "home", or an explicit region location).
 * region_x - The x grid coordinate of the start region in meters. So a region at map co-ordinate 1000 will have a grid co-ordinate of 256000.
 * region_y - The y grid coordinate of the start region in meters.
 * region_size_x - The x size of the start region in meters. Usually this will be 256 but with a varregion this can be a multiple of 256.
 * region_size_y - The y size of the start region in meters. Usually this will be 256 but with a varregion this can be a multiple of 256.
 * circuit_code - Circuit code to use for all UDP connections.
 * session_id - The UUID of this session.
 * secure_session_id - The secure UUID of this session.
 * inventory-root - The ID of the user's root folder (which appears as the "My Inventory" folder in most viewers).
 * inventory-skeleton - Details about the child folders of the root folder. Each entry has the following parameters.
 * folder_id - The ID of the folder.
 * parent_id - The ID of the containing folder.
 * name - The name of the folder.
 * type_default - The type of the folder. These values correspond to the InventoryType class in libopenmetaverse, where -1 is an ordinary untyped folder.
 * version - The version number of the folder. This is increment on operations that change the folder's contents.  A viewer can cache these version numbers and other inventory information so that it can reduce the amount of inventory data that it has to request.
 * inventory-lib-root - The ID of the library root folder (which appears as the "OpenSim Library" folder in most viewers).
 * inventory-skel-lib - Details about the child folders of the library root folder. Has the same format as inventory-skeleton above.
 * inventory-lib-owner - The ID of the user that owns the library.
 * map-server-url - URL from which to request map tiles.
 * buddy-list - The user's friend list. This contains an entry for each friend (buddy).  These entries have the following parameters.
 * buddy_id - The UUID of the friend.
 * buddy_rights_given - The rights that the friend has granted to this user. The value corresponds to the FriendsRights enum in libopenmetaverse.
 * buddy_rights_has - The rights that this user has granted to the friend. The value corresponds to the FriendsRights enum in libopenmetaverse.
 * gestures - The gestures that the user currently has active. If there any, each entry has the following parameters
 * item_id - The item ID of the gesture in the user's inventory.
 * asset_id - The asset ID of the gesture.
 * initial-outfit - You would think this would correspond to user's initial outfit. However, OpenSimulator always sends back an entry with folder_name "Nightclub Female" and gender "female" with no obvious ill effect.  Can probably be ignored.
 * global-textures - Unknown if this is used any longer. OpenSimulator always sets
 * cloud_texture_id as dc4b9f0b-d008-45c6-96a4-01dd947ac621.
 * sun_texture_id as cce0f112-878f-4586-a2e2-a8f104bba271.
 * moon_texture_id as ec4b9f0b-d008-45c6-96a4-01dd947ac621.
 * login - Function unknown. OpenSimulator always sets this to "true".
 * login-flags - Some extra information about login. Of these
 * stipend_since_login - probably shows whether a user received stipend money since their last login. OpenSimulator always sets this to "N".
 * ever_logged_in - indicates whether the account has ever logged in. Currently, OpenSimulator always sets this to "Y" even if the user has never logged in before.
 * seconds_since_epoch - server time in Unix seconds since epoch format (i.e. seconds since 1970).
 * daylight_savings - whether daylight savings is considered to be in effect for the grid time. OpenSimulator can set this to "Y" or "N".
 * gendered - Function unknown, possibly relating to avatars. OpenSimulator always sets this to "Y".
 * message - Message that can be displayed to the user when logging in.
 * ui-config - Function unknown. OpenSimulator only has one setting here.
 * allow_first_life - always set to "Y" by OpenSimulator. Could possibly control whether the First Life tab is shown for user profiles (now obsolete in some circumstances).
 * event_categories - Function unknown, probably relates to events. OpenSimulator does not currently set this.
 * classified_categories - Classified categories. OpenSimulator currently always adds the categories

Code
The parts of OpenSimulator that handle steps 1 and 2 can be found in OpenSim.Services.LLLoginService package.