OpenSimulator - User contributions [en]

RemoteAdmin:RemoteAdmin Standards

2013-12-03T17:44:24Z

Michelle Argus: /* common Parameters are */

__NOTOC__
{{Quicklinks}}
 

POLICY PROPOSAL:
This document is a proposal for naming standards and is not yet active.

Base Syntax: admin_Category_Function

= Naming =
Function and parameter names should use US English spelling. 

Function should be clearly named & indicative of purpose

== Parameters ==
Parameters should be clearly named & use a common syntax

Eg.
use ''region_id'' and NOT region_uuid, region_ID or any other variation

=== common Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''region_id'' - uuid of a region
* ''region_name'' - name of a region
* ''filename'' - name and location of a file eg. "c:/bin/my_backup.oar", "my_backup.oar", "http://www.foo.bar/my_backup.oar"
* ''agent_first_name'', ''agent_last_name'' - name of avatar
* ''agent_id'' - uuid of an avatar
* ''user_firstname'', ''user_lastname'' - name of user's account
* ''user_password'' - password of user's account
* ''object_id'' - uuid of an object
* ''object_name'' - name of an object

=== commonly returned Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''success'' - returns true/false when a function is executed
* ''error'' - returns the error message when an error occures

[[RemoteAdmin]]

RemoteAdmin:admin teleport agent

2013-11-17T01:32:31Z

Michelle Argus: /* PHP */ removed unwanted tag

'''admin_teleport_agent''' remotely teleport an agent to a given region and/or position

=== Enabling admin_teleport_agent ===
If not all functions are enabled, use admin_create_teleport_agent to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_teleport_agent,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region
|
|-
| ''agent_id''
| agent uuid, optionaly agent_first_name and agent_last_name
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''agent_first_name''
| first name of agent
|
|-
| ''agent_last_name''
| last name of agent
|
|-
| ''pos_x''
| teleport to region position x
|
|-
| ''pos_y''
| teleport to region position y
|
|-
| ''pos_z''
| teleport to region position z
|
|-
| ''lookat_x''
| look in direction x
|
|-
| ''lookat_y''
| look in direction y
|
|-
| ''lookat_z''
| look in direction z
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
|
| true
|}

=== Error messages ===
No error messages

== Notes ==
* From commit 415b7b7 on Wed 7 Dec 2011 (OpenSimulator 0.7.3-dev)

== Example ==
=== PHP ===
This example needs the RemoteAdmin PHP Class file available [http://code.google.com/p/opensimtools/wiki/RemoteAdminPHPClass here].

<source lang="php">
<?php

This example needs the RemoteAdmin PHP Class file available [http://code.google.com/p/opensimtools/wiki/RemoteAdminPHPClass here]. <source lang="php">

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_teleport_agent (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'user_firstname' => 'John', 'user_lastname' => 'Doe', 'pos_x' => '15', 'pos_y' => '10');
$myRemoteAdmin->SendCommand('admin_teleport_agent', $parameters);
?>
</source>

=== Python ===

<source lang="python">
#!/usr/bin/python
import xmlrpclib

# XML-RPC URL (http_listener_port)
simulatorURL = "http://127.0.0.1:5000"

# instantiate server object
simulator = xmlrpclib.Server(simulatorURL)

# invoke admin_alert: requires password and message
simulator.admin_teleport_agent({'password':'secret', 'agent_first_name':'John','agent_last_name':'Doe','region_name':'My Plaza', 'pos_x':'15', 'pos_y':'10'})
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

Remoteadmin:admin get agents

2013-11-17T01:27:23Z

Michelle Argus: /* PHP 2 */

'''admin_get_agents''' get information about agents in a given region

=== Enabling admin_get_agents ===
If not all functions are enabled, use admin_get_agents to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_get_agents,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the region to look for agents (or region_id below)
|
|-
| ''region_id''
| UUID of the region to look for agents (or region_name above)
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''include_children''
| If true, then return information about [[Glossary#C|child agents]] as well as [[Glossary#R|root agents]].
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

===Root===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
|
| true
|-
| ''regions'' || Regions for which information is returned. || See regions
|}

===Regions===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| name || Name of region ||
|-
| id || UUID of region ||
|-
| agents || Agents found in the region requested. || See agents
|}

===Agents===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| name || Name of agent ||
|-
| type || Type of agent || Npc or User
|-
| id || UUID of agent ||
|-
| current_parcel_id || UUID of parcel the agent is currently over ||
|-
| pos_x || X position of the agent ||
|-
| pos_y || Y position of the agent ||
|-
| pos_z || Z position of the agent ||
|-
| vel_x || X velocity of the agent ||
|-
| vel_y || Y velocity of the agent ||
|-
| vel_z || Z velocity of the agent ||
|-
| lookat_x || X gaze direction of the agent ||
|-
| lookat_y || X gaze direction of the agent ||
|-
| lookat_z || X gaze direction of the agent ||
|-
| is_sat_on_ground || true if the agent is sat on the ground ||
|-
| is_sat_on_object || true if the agent is sat on an object ||
|-
| is_flying || true if the agent is flying ||
|}

=== Error messages ===
No error messages

== Notes ==
* This was introduced in git master commit 3072f25 (OpenSimulator 0.7.6 development).

== Examples ==
=== Output ===
<pre>
(
[regions] => Array
(
[0] => Array
(
[agents] => Array
(
[0] => Array
(
[lookat_y] => 0.04238708
[lookat_z] => 0
[is_sat_on_ground] => False
[type] => User
[current_parcel_uuid] => fc2f2820-7181-4a9f-8cba-f73d3e14f72e
[name] => John Joe
[uuid] => bb293b8c-4986-4ab4-844a-5d22639f2d75
[vel_y] => 0
[vel_z] => 0
[is_flying] => False
[is_sat_on_object] => False
[pos_x] => 134.6547
[pos_y] => 122.7092
[pos_z] => 25.27129
[vel_x] => 0
[lookat_x] => 0.9991013
)

)

[uuid] => 11111111-bf88-45ac-aace-35bd76426c81
[name] => test one
)

)

[success] => 1
)
</pre>

=== PHP 1 ===

This example needs the RemoteAdmin PHP Class file available [http://code.google.com/p/opensimtools/wiki/RemoteAdminPHPClass here].

<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_save_oar (multiple parameters)
$parameters = array('password' => 'plop', 'region_name' => 'test one', 'include_children' => 'false');
$response = $myRemoteAdmin->SendCommand('admin_get_agents', $parameters);

print_r($response);
?>
</source>

=== PHP 2 ===

<source lang="php">
<?php
$request = xmlrpc_encode_request("admin_get_agents", array("password" => "plop", "region_name" => "test one", "include_children" => "false"));

$context = stream_context_create(array('http' => array(
'method' => "POST",
'header' => "Content-Type: text/xml\r\nConnection: close\r\n",
'content' => $request
)));

$fp = fopen("http://localhost:5000", 'rb', false, $context);
$file = stream_get_contents($fp);
fclose($fp);

$response = xmlrpc_decode($file);
if ($response && xmlrpc_is_fault($response)) {
trigger_error("xmlrpc: $response[faultString] ($response[faultCode])");
} else {
print_r($response);
}
?>
</source>

= See Also =

* [[Server Commands]]

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

Remoteadmin:admin get agents

2013-11-17T01:25:52Z

Michelle Argus: added missing example using RemoteAdmin PHP Class file

'''admin_get_agents''' get information about agents in a given region

=== Enabling admin_get_agents ===
If not all functions are enabled, use admin_get_agents to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_get_agents,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the region to look for agents (or region_id below)
|
|-
| ''region_id''
| UUID of the region to look for agents (or region_name above)
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''include_children''
| If true, then return information about [[Glossary#C|child agents]] as well as [[Glossary#R|root agents]].
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

===Root===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
|
| true
|-
| ''regions'' || Regions for which information is returned. || See regions
|}

===Regions===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| name || Name of region ||
|-
| id || UUID of region ||
|-
| agents || Agents found in the region requested. || See agents
|}

===Agents===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| name || Name of agent ||
|-
| type || Type of agent || Npc or User
|-
| id || UUID of agent ||
|-
| current_parcel_id || UUID of parcel the agent is currently over ||
|-
| pos_x || X position of the agent ||
|-
| pos_y || Y position of the agent ||
|-
| pos_z || Z position of the agent ||
|-
| vel_x || X velocity of the agent ||
|-
| vel_y || Y velocity of the agent ||
|-
| vel_z || Z velocity of the agent ||
|-
| lookat_x || X gaze direction of the agent ||
|-
| lookat_y || X gaze direction of the agent ||
|-
| lookat_z || X gaze direction of the agent ||
|-
| is_sat_on_ground || true if the agent is sat on the ground ||
|-
| is_sat_on_object || true if the agent is sat on an object ||
|-
| is_flying || true if the agent is flying ||
|}

=== Error messages ===
No error messages

== Notes ==
* This was introduced in git master commit 3072f25 (OpenSimulator 0.7.6 development).

== Examples ==
=== Output ===
<pre>
(
[regions] => Array
(
[0] => Array
(
[agents] => Array
(
[0] => Array
(
[lookat_y] => 0.04238708
[lookat_z] => 0
[is_sat_on_ground] => False
[type] => User
[current_parcel_uuid] => fc2f2820-7181-4a9f-8cba-f73d3e14f72e
[name] => John Joe
[uuid] => bb293b8c-4986-4ab4-844a-5d22639f2d75
[vel_y] => 0
[vel_z] => 0
[is_flying] => False
[is_sat_on_object] => False
[pos_x] => 134.6547
[pos_y] => 122.7092
[pos_z] => 25.27129
[vel_x] => 0
[lookat_x] => 0.9991013
)

)

[uuid] => 11111111-bf88-45ac-aace-35bd76426c81
[name] => test one
)

)

[success] => 1
)
</pre>

=== PHP 1 ===

This example needs the RemoteAdmin PHP Class file available [http://code.google.com/p/opensimtools/wiki/RemoteAdminPHPClass here].

<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_save_oar (multiple parameters)
$parameters = array('password' => 'plop', 'region_name' => 'test one', 'include_children' => 'false');
$response = $myRemoteAdmin->SendCommand('admin_get_agents', $parameters);

print_r($response);
?>
</source>

=== PHP 2 ===

<source lang="php">
$request = xmlrpc_encode_request("admin_get_agents", array("password" => "plop", "region_name" => "test one", "include_children" => "false"));

$context = stream_context_create(array('http' => array(
'method' => "POST",
'header' => "Content-Type: text/xml\r\nConnection: close\r\n",
'content' => $request
)));

$fp = fopen("http://localhost:5000", 'rb', false, $context);
$file = stream_get_contents($fp);
fclose($fp);

$response = xmlrpc_decode($file);
if ($response && xmlrpc_is_fault($response)) {
trigger_error("xmlrpc: $response[faultString] ($response[faultCode])");
} else {
print_r($response);
}
?>
</source>

= See Also =

* [[Server Commands]]

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

Remoteadmin:admin get agents

2013-11-17T01:17:57Z

Michelle Argus: Adjusted formating to match with other commands

'''admin_get_agents''' get information about agents in a given region

=== Enabling admin_get_agents ===
If not all functions are enabled, use admin_get_agents to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_get_agents,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the region to look for agents (or region_id below)
|
|-
| ''region_id''
| UUID of the region to look for agents (or region_name above)
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''include_children''
| If true, then return information about [[Glossary#C|child agents]] as well as [[Glossary#R|root agents]].
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

===Root===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
|
| true
|-
| ''regions'' || Regions for which information is returned. || See regions
|}

===Regions===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| name || Name of region ||
|-
| id || UUID of region ||
|-
| agents || Agents found in the region requested. || See agents
|}

===Agents===

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| name || Name of agent ||
|-
| type || Type of agent || Npc or User
|-
| id || UUID of agent ||
|-
| current_parcel_id || UUID of parcel the agent is currently over ||
|-
| pos_x || X position of the agent ||
|-
| pos_y || Y position of the agent ||
|-
| pos_z || Z position of the agent ||
|-
| vel_x || X velocity of the agent ||
|-
| vel_y || Y velocity of the agent ||
|-
| vel_z || Z velocity of the agent ||
|-
| lookat_x || X gaze direction of the agent ||
|-
| lookat_y || X gaze direction of the agent ||
|-
| lookat_z || X gaze direction of the agent ||
|-
| is_sat_on_ground || true if the agent is sat on the ground ||
|-
| is_sat_on_object || true if the agent is sat on an object ||
|-
| is_flying || true if the agent is flying ||
|}

=== Error messages ===
No error messages

== Notes ==
* This was introduced in git master commit 3072f25 (OpenSimulator 0.7.6 development).

== Examples ==
=== Output ===
<pre>
(
[regions] => Array
(
[0] => Array
(
[agents] => Array
(
[0] => Array
(
[lookat_y] => 0.04238708
[lookat_z] => 0
[is_sat_on_ground] => False
[type] => User
[current_parcel_uuid] => fc2f2820-7181-4a9f-8cba-f73d3e14f72e
[name] => John Joe
[uuid] => bb293b8c-4986-4ab4-844a-5d22639f2d75
[vel_y] => 0
[vel_z] => 0
[is_flying] => False
[is_sat_on_object] => False
[pos_x] => 134.6547
[pos_y] => 122.7092
[pos_z] => 25.27129
[vel_x] => 0
[lookat_x] => 0.9991013
)

)

[uuid] => 11111111-bf88-45ac-aace-35bd76426c81
[name] => test one
)

)

[success] => 1
)
</pre>

=== PHP ===
This example needs the RemoteAdmin PHP Class file available [http://code.google.com/p/opensimtools/wiki/RemoteAdminPHPClass here]. <source lang="php">

<source lang="php">
$request = xmlrpc_encode_request("admin_get_agents", array("password" => "plop", "region_name" => "test one", "include_children" => "false"));

$context = stream_context_create(array('http' => array(
'method' => "POST",
'header' => "Content-Type: text/xml\r\nConnection: close\r\n",
'content' => $request
)));

$fp = fopen("http://localhost:5000", 'rb', false, $context);
$file = stream_get_contents($fp);
fclose($fp);

$response = xmlrpc_decode($file);
if ($response && xmlrpc_is_fault($response)) {
trigger_error("xmlrpc: $response[faultString] ($response[faultCode])");
} else {
print_r($response);
}
?>
</source>

= See Also =

* [[Server Commands]]

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin save heightmap

2013-08-16T09:01:56Z

Michelle Argus: /* Parameters */

'''admin_save_heightmap''' remotely allows to save a hight map of the regions to file.

=== Enabling admin_save_heightmap ===
If not all functions are enabled, use admin_save_heightmap to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_save_heightmap,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the region, optionaly use ''region_id''
|
|-
| ''filename''
| save height map as file name
|
|}

=== Optional Parameters ===
These parameters are optional
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid of the region.
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true
|}

=== Error messages ===
When an error occures the following error value are returned

*

== Notes ==
* ''accepted'' is an returned parameter, probably used prior to ''success''

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_save_heightmap (multiple parameters)
$parameters = array('regionid' => '000000-0000-0000-0000-00000000', 'filename' => 'my_terrain.raw');
$myRemoteAdmin->SendCommand('admin_save_heightmap', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin load heightmap

2013-08-16T09:00:54Z

Michelle Argus: /* Parameters */

'''admin_load_heightmap''' remotely allows to load a hight map files to a region.

=== Enabling admin load_heightmap ===
If not all functions are enabled, use admin_load_heightmap to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_load_heightmap,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the region, optionaly use ''region_id''
|
|-
| ''filename''
| file name of terrain file
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid of the region.
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true
|-
|''error''
| error message when not successfull
|
|}

=== Error messages ===
When an error occures the following error value are returned

* terrain module not available

== Notes ==
* Terrain files can also be loaded via web, were the filename is the full webadress.
* ''accepted'' is an returned parameter, probably used prior to ''success''

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_load_heightmap (multiple parameters)
$parameters = array('regionid' => '000000-0000-0000-0000-00000000', 'filename' => 'my_terrain.raw');
$myRemoteAdmin->SendCommand('admin_load_heightmap', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

Logging

2013-08-15T00:01:49Z

Michelle Argus: /* Changing logging levels before startup */

__NOTOC__
{{Quicklinks}}
 

== Changing logging levels before startup ==

OpenSimulator uses the [http://logging.apache.org/log4net/ log4net] package for logging. This means that every executable you run for OpenSimulator has an accompanying .config file which contains the logging configuration

For instance, the OpenSim.exe.config file looks like this.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net" />
</configSections>
<appSettings>
</appSettings>
<log4net>
<appender name="Console" type="OpenSim.Framework.Console.OpenSimAppender, OpenSim.Framework.Console">
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date{HH:mm:ss} - %message%newline" />
</layout>
</appender>

<appender name="LogFileAppender" type="log4net.Appender.FileAppender">
<file value="OpenSim.log" />
<appendToFile value="true" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date %-5level - %logger %message%newline" />
</layout>
</appender>


<logger name="NHibernate" additivity="false">
<level value="INFO"/>
<appender-ref ref="NHibernateFileLog"/>
</logger>

<root>
<level value="DEBUG" />
<appender-ref ref="Console" />
<appender-ref ref="LogFileAppender" />
</root>
</log4net>
</configuration>

This looks rather complicated, but if you want to change the level of messages logged, then you could change the value in the <root> section (right at the end) which is

<level value="DEBUG" />

in the example above to something different, e.g.

<level value="WARN" />

which will only display warning and error level log messages. Permissible values are ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF

You can also see from the OpenSim.exe.config file that log files are written to OpenSim.log (as well as the console).

=== Rolling file appender and maximum log-file size ===

Log4net provides several log-file appenders. One of them is the ''RollingFileAppender'', which limits log-file size and rotates log-files automatically. To use this appender, add the following section to the log4net-configuration:

<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
<file value="OpenSim.log" />
<appendToFile value="true" />
<maximumFileSize value="1000KB" />
<maxSizeRollBackups value="2" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date %-5level - %logger %message%newline" />
</layout>
</appender>

The maximum size can be set in the ''maximumFileSize'' element, the ''maxSizeRollBackups'' element determines the maximum number of rolling log-files. So, the setting above will create a log-file named ''OpenSim.log'' with a maximum size of 1000KB. When the limit is reached, ''OpenSim.log'' will be renamed to ''OpenSim.log.1'', and a fresh ''OpenSim.log'' is started (possibly after renaming ''OpenSim.log.1'' to ''OpenSim.log.2'', should that file exist already).

To use the appender defined above, replace the line
<appender-ref ref="LogFileAppender" />
by
<appender-ref ref="RollingFileAppender" />

Further information about configuration of log4net can be found on the [http://logging.apache.org/log4net/release/manual/configuration.html Log4Net configuration page].

=== More specialized requirements ===
As an example, similar to [http://opensimulator.org/mantis/view.php?id=2603 Mantis#2603], if you want logging the [[XEngine]]'s DEBUG output into a separate file ''xengine.log'', and let only the message with level INFO and higher appear on the console, you can do that by adding the following lines to your ''OpenSim.exe.config'':

<appender name="XengineLogFileAppender" type="log4net.Appender.FileAppender">
<file value="xengine.log" />
<appendToFile value="true" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date %-5level - %logger %message%newline" />
</layout>
</appender>

<appender name="XengineConsole" type="OpenSim.Framework.Console.OpenSimAppender, OpenSim.Framework.Console">
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date{HH:mm:ss} - %message%newline" />
</layout>
<filter type="log4net.Filter.LevelRangeFilter">
<levelMin value="INFO" />
<levelMax value="FATAL" />
</filter>
</appender>

<logger name="OpenSim.Region.ScriptEngine.XEngine.XEngine" additivity="false">
<appender-ref ref="XengineLogFileAppender" />
<appender-ref ref="XengineConsole" />
</logger>

(if there is a shorter way to do it, please replace those lines above) ;-)

Or, as an easier example, if you want to have the normal logging, except for the HttpServers which you want only INFO messages for, you can add the following lines after the ''</root>''-tag:

<logger name="OpenSim.Framework.Servers.HttpServerLogWriter">
<level value="INFO" />
</logger>

=== MySQL Logging ===
This example can be used to log the data to a MySQL table.

Step 1: Create a MySQL Database "OSLog" and add the following table to which the data will be stored to

CREATE TABLE `opensim_log` (
`ID` int(10) NOT NULL AUTO_INCREMENT,
`DATE` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
`Level` varchar(100) DEFAULT '',
`Logger` varchar(512) DEFAULT '',
`Message` varchar(1000) DEFAULT '',
PRIMARY KEY (`ID`)
);

Step 2: Replace the "LogFileAppender" appender Section with

<appender name="MySql_ADONetAppender" type="log4net.Appender.ADONetAppender">
<bufferSize value="5" />
<lossy value="false"/>
<connectionType value="MySql.Data.MySqlClient.MySqlConnection, MySql.Data"/>
<connectionString value="Server=localhost;Database=OSLog;Uid=DBUsername;Pwd=DBUserPassword"/>
<commandText value="INSERT INTO opensim_log(Date,Level,Logger,Message) VALUES (@log_date, @log_level, @logger, @message)"/>
<parameter>
<parameterName value="@log_date"/>
<dbType value="DateTime"/>
<layout type="log4net.Layout.RawTimeStampLayout"/>
</parameter>
<parameter>
<parameterName value="@log_level"/>
<dbType value="String"/>
<size value="512"/>
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%level"/>
</layout>
</parameter>
<parameter>
<parameterName value="@logger"/>
<dbType value="String"/>
<size value="512"/>
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%logger"/>
</layout>
</parameter>
<parameter>
<parameterName value="@message"/>
<dbType value="String"/>
<size value="1000"/>
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%message"/>
</layout>
</parameter>
</appender>

To use the appender defined above, replace the line
<appender-ref ref="LogFileAppender" />
by
<appender-ref ref="MySql_ADONetAppender" />

Note: One also can continue logging to File, in which case we do not need to replace the LogFileAppender section.

== Setting log levels during runtime ==

It isn't currently possible to change the level of logging to the log file during runtime. However, it is possible to change the level sent to the console. You can do this by executing the

set log level [<level>]

command. For example

set log level error

will mean only errors are sent to the console. The log still receives messages that meet the level set in the OpenSim.exe.config file at startup.

Not specifying any level will tell you what the current console logging level is.

Changes to the log level sent to the console will not persist over restarts. If you want the change to be permanent, you can set a threshold value in the ConsoleAppender in a config file such as OpenSim.exe.config as described above.

== Specifying log file location per instance ==

Logging for multiple instances run from a single OpenSim.exe isn't something that the default log4net configuration handles. Fortunately, log4net accepts environment variables. This allows a script wrapping OpenSim.exe to specify a log location by setting an environment variable. An example snippet for ''Opensim.exe.config'' might be:

<appender name="LogFileAppender" type="log4net.Appender.FileAppender">
<file value="${OSIM_LOGPATH}\OpenSim.log" />
<appendToFile value="true" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date %-5level - %logger %message%newline" />
</layout>
</appender>

RemoteAdmin:RemoteAdmin Proposals

2013-06-30T07:40:17Z

Michelle Argus: /* RemoteAdmin Proposal Table */

{{Quicklinks}}
{{proposal}}
{{content}}

== Introduction ==

This is a page dedicated to OpenSim's remote administration module

<big>'''Please see [[RemoteAdmin:RemoteAdmin Standards|RemoteAdmin Standards]] for proposed naming schema'''</big>

* Please post your Function along with a brief description of what it would be for, or do and an example of it.
* Make sure it begins with admin_.
* And remember, almost anything within reason can be posted here as an idea, who knows, maybe a variation of your request can be possible.
* Consider posting your proposal to [http://opensimulator.org/mantis/ Mantis] so that we can smoothly discuss about it. After that, add the link to mantis issue in the description.

== RemoteAdmin Proposal Table ==

{| class="sortable" cellpadding="5" cellspacing="0" style="width:100%;border:1px solid #000000;border-collapse: collapse; white-space:normal;"
|- style="background-color:#99CCFF;font-size:6pt;font-weight:bold;border-bottom:1px solid;" align="center" valign="bottom"
| Function
| Description
| Example Usage
| Signed
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_teleport_all_agents
| Teleports all agents in a simulator or specifyed region to a region/position
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_save_iar
| executes the Save IAR command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_quit_region
| close region without removing region from the map.
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_load_iar
| executes the Load IAR command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_fcache_clear
| executes the fcache clear command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_get_windlight_scene
| get windlight settings
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_windlight_scene
| set windlight settings
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_windlight_scene_targeted
| set windlight settings for target agent
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_region_stats
| quary the region stats, similar to osGetRegionStats
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_log_level
| change the log level of the console, eg when problems occure
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_backup
| executes the backup command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_config_get
| executes the config get command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_export_map
| executes the export map command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_kill_uuid
| executes the kill uuid command
|
| Michelle Argus
|}

RemoteAdmin:admin estate reload

2013-05-09T09:54:52Z

Michelle Argus: /* Notes */

'''admin_estate_reload''' remotely allows to reload estate settings of all regions in the simulator. This can be used to update the estate settings if they have changed on another simulator or database.

=== Enabling admin_estate_reload ===
If not all functions are enabled, use admin_estate_reload to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_estate_reload,...
</source>

== Parameters ==
=== Required Parameters ===
No parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

=== Optional Parameters ===
No optional parameter

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|}

=== Error messages ===
No error messages

== Notes ==
* From commit 90f03c on Mon 6 May 2013 (OpenSimulator 0.7.5-dev)

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_estate_reload
$myRemoteAdmin->SendCommand('admin_estate_reload', array());
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin estate reload

2013-05-09T09:54:25Z

Michelle Argus: /* Error messages */

'''admin_estate_reload''' remotely allows to reload estate settings of all regions in the simulator. This can be used to update the estate settings if they have changed on another simulator or database.

=== Enabling admin_estate_reload ===
If not all functions are enabled, use admin_estate_reload to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_estate_reload,...
</source>

== Parameters ==
=== Required Parameters ===
No parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

=== Optional Parameters ===
No optional parameter

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|}

=== Error messages ===
No error messages

=== Notes ===
* From commit 90f03c on Mon 6 May 2013 (OpenSimulator 0.7.5-dev)

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_estate_reload
$myRemoteAdmin->SendCommand('admin_estate_reload', array());
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin estate reload

2013-05-09T09:53:10Z

Michelle Argus: /* Notes */

'''admin_estate_reload''' remotely allows to reload estate settings of all regions in the simulator. This can be used to update the estate settings if they have changed on another simulator or database.

=== Enabling admin_estate_reload ===
If not all functions are enabled, use admin_estate_reload to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_estate_reload,...
</source>

== Parameters ==
=== Required Parameters ===
No parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

=== Optional Parameters ===
No optional parameter

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|}

=== Error messages ===
No error messages

* From commit 90f03c on Mon 6 May 2013 (OpenSimulator 0.7.5-dev)

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_estate_reload
$myRemoteAdmin->SendCommand('admin_estate_reload', array());
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin estate reload

2013-05-09T09:27:19Z

Michelle Argus: Created page with "'''admin_estate_reload''' remotely allows to reload estate settings of all regions in the simulator. This can be used to update the estate settings if they have changed on anothe..."

'''admin_estate_reload''' remotely allows to reload estate settings of all regions in the simulator. This can be used to update the estate settings if they have changed on another simulator or database.

=== Enabling admin_estate_reload ===
If not all functions are enabled, use admin_estate_reload to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_estate_reload,...
</source>

== Parameters ==
=== Required Parameters ===
No parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

=== Optional Parameters ===
No optional parameter

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|}

=== Error messages ===
No error messages

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_estate_reload
$myRemoteAdmin->SendCommand('admin_estate_reload', array());
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin

2013-05-09T09:19:38Z

Michelle Argus: /* Estate management */

{{Quicklinks}}

== Introduction ==

RemoteAdmin is an interface for simulators that allows various operations to be executed from outside the simulator. '''Operations that relate to the simulator itself (e.g teleport user) are always available. Those that relate to grid services (user creation and updating) are only available in standalone mode. In grid mode, one has to use ROBUST level [[UserManipulation]] capabilities instead.'''

== How to Setup the Remote Admin interface ==

First you should enable the remote admin interface to do so just add the following lines to your OpenSim.ini file Port should be set to a nonzero value to have the remote admin on a different port

As of r/16843 you can limit access to remote admin to specific IP addresses by using the optional access_ip_addresses. You can list all IP's allowed to access remote admin by seperating each IP by a comma. If access_ip_addresses isn't set, then all IP addresses can access RemoteAdmin.

[RemoteAdmin]
enabled = true
access_password = secret
enabled_methods = all

See OpenSim.ini.example in the OpenSimulator distribution for more details.

=== Further options ===

You can also specify a different port for the XMLRPCAdmin command listener from the default simulator HTTP port

[RemoteAdmin]
port = <port-number>

== RemoteAdmin Commands ==
<div style="background-color:#ffa0a0; padding:15px">
'''Caution ! All commands using parameters for the uuid of a region use "region_id" as parameter. All other parameters eg. region_uuid or regionID will be removed after June 2012'''
</div>

=== Agent management ===
*[[Remoteadmin:admin teleport agent|admin_teleport_agent]]
*[[Remoteadmin:admin get agents|admin_get_agents]] (post OpenSimulator 0.7.5)

=== User management ===
*[[RemoteAdmin:admin create user|admin_create_user]]
*[[RemoteAdmin:admin create user email|admin_create_user_email]]
*[[RemoteAdmin:admin exists user|admin_exists_user]]
*[[RemoteAdmin:admin update user|admin_update_user]]

=== Object management ===

=== Parcel management ===

=== Region management ===
*[[RemoteAdmin:admin broadcast|admin_broadcast]]
*[[RemoteAdmin:admin close region|admin_close_region]]
*[[RemoteAdmin:admin create region|admin_create_region]]
*[[RemoteAdmin:admin delete region|admin_delete_region]]
*[[RemoteAdmin:admin modify region|admin_modify_region]]
*[[RemoteAdmin:admin region query|admin_region_query]]
*[[RemoteAdmin:admin restart|admin_restart]]
*[[RemoteAdmin:admin shutdown|admin_shutdown]]

=== Region file management ===
{{multicol}}
* [[RemoteAdmin:admin load heightmap|admin_load_heightmap]]
* [[RemoteAdmin:admin load oar|admin_load_oar]]
* [[RemoteAdmin:admin load xml|admin_load_xml]]
* [[RemoteAdmin:admin save heightmap|admin_save_heightmap]]
* [[RemoteAdmin:admin save oar|admin_save_oar]]
* [[RemoteAdmin:admin save xml|admin_save_xml]]

=== Region access management ===
* [[RemoteAdmin:admin acl list|admin_acl_list]]
* [[RemoteAdmin:admin acl clear|admin_acl_clear]]
* [[RemoteAdmin:admin acl add|admin_acl_add]]
* [[RemoteAdmin:admin acl remove|admin_acl_remove]]

=== Estate management ===
* [[RemoteAdmin:admin estate reload|admin_estate_reload]]

=== Administration ===
* [[RemoteAdmin:admin console command|admin_console_command]]

== Subcategories ==

* [[RemoteAdmin:RemoteAdmin Examples|RemoteAdmin Examples]]
* [[RemoteAdmin:RemoteAdmin Proposals|RemoteAdmin Proposals]]
* [[RemoteAdmin:RemoteAdmin Standards|RemoteAdmin Standards]]
* [[RemoteAdmin:RemoteAdmin Implement new command|RemoteAdmin How to implement new commands]]

[[Category:Development]]
[[Category:RemoteAdmin]]

Feature Proposals/Improve Groups Service

2012-11-15T18:03:44Z

Michelle Argus: /* D) Groups service distributes IM */

=Date=

October 2012

= Status =

In progress

= Proposers =

* Michelle Argus
* Justin Clark-Casey (justincc)

= Introduction =

This may encompass many improvements to groups, but the first is to cache login information in groups to improve group IM, such that an IM isn't sent to every single user, even those offline.

= A) Proposal - Simulator tells group service about user login/logout =

Please see mailing-list e-mails [1], [2] and [5]. The changes for OpenSimulator and XmlRpcGroups are in [3] and [4].

These changes send login status information and time to the groups service from the simulator. This allows an extra 'offline' parameter to be passed to GetGroupMembers to control whether all or only online members of a group are returned.

'''PROS''':

* Only a single network call (which may be cached for a period) required on each group IM.
* Reasonably simple.
* May allow messaging across multiple OpenSimulator installations.

'''CONS''':

* Extra calls to groups service on each login/logout.
* Groups service has to cache extra information.
* Cached information not reuseable by other services.
* Accuracy of login status is dependant on groupsettings of each simulator within a grid (multiple groups possible in open grids like OSGrid).

= Alternatives =

== B) Simulator queries presence service on IM ==

One alternative is for the simulator to fetch group information and then query which group members are online when an IM is sent to a group.

'''This is current implemented as an experimental option (see status section below).'''

'''PROS''':

* Groups service doesn't need to handle online status.
* One source of online status truth that cannot become inconsistent with information cached in the groups service.
* Other services can also use the same simulator-side group users online caching, though this may not be a big factor.
* Groups service data can be backed up without any possible worries about inconsistent online status if it needs to be restored.

'''CONS''':

* Every group IM still requires an extra network call to GridUser services via the simulator, though this would be mitigated by short-term caching.
* Comparatively complex.
* If code external to OpenSimulator wanted to know online users for a group, it would have to call Presence service (and possibly cache information) itself rather than just being able to query the groups service.
* Inconsistency between presence service and groups service online information may not be important - possibly the worst that could happen is some users do not receive group members until they relog.

== C) Groups services queries presence service on members online request ==

Similar to Alternative B, the group service requests the login status of the members from the gridservices instead of the simulator. Like the original proposal, this requires modifications to the groups service interface to add a "request users online only" bool.

'''PROS''':

* Simulator doesn't need to handle online status.
* One source of online status truth that cannot become inconsistent with information cached in the groups service.
* Groups service data can be backed up without any possible worries about inconsistent online status if it needs to be restored.
* Fast data connection between grid and group server
* All group related services can use the login data

'''CONS''':

* Every group IM still requires an extra network call to GridUser services via the group service, though the results could be cached for a short period of time (e.g. 20 seconds).
* Comparatively complex.
* Inconsistency between presence service and groups service online information may not be important - possibly the worst that could happen is some users do not receive group members until they relog.

== D) Groups service distributes IM ==

Instead of distributing the message itself, the simulator passes the group IM data on to the groups service. The groups service handles message distribution to group members.

The login status could be handled by the simulator, grid services or group service (see A, B and C).

'''PROS''':

* Central service, which makes for easier management.
* Only one request is sent to the group service - ''How is this a pro? We are already sending only one request to the groups service on each IM with the other options [[User:Justincc|Justincc]] 03:14, 8 November 2012 (UTC)'' ''The Simulator request currently requests the members, then it requests online status and then it sends the IMs. We currently have atleast 3 request. If the IM is passed on, then the simulator makes only 1 request, while the IM service handles the other requests [[User:Michelle Argus|Michelle Argus]] 15 November 2012''
* Message sending load is removed from the simulator.
* The group server can be ajusted better as its sole purpose is to manage the grouprelated work ''Could you elaborate? [[User:Justincc|Justincc]] 03:15, 8 November 2012 (UTC)'' ''A Simulator has to deal with many things eg. physics, scriptengine etc and thus the server has a more general setup sothat everything works. The less funktions a simulator has to run, the better one can fine tune the server setup for each of those funktion. Same also aplies for a IM service[[User:Michelle Argus|Michelle Argus]]''
* Spam and illegal activity can be filtered gridwide.

'''CONS''':

* Load on the group service is significantly increased as the load of group IM sending is now concentrated at the service rather than distributed among simulators.
* Laws governing data protection and data security could be abused by grid management. ''Not sure this is a strong reason, as this could already be captured at simulator level. However, privacy concerns are worth mentioning. [[User:Justincc|Justincc]] 03:17, 8 November 2012 (UTC)'' ''In open grids the grid management has no control over what module is used/modded by the simulator hoster. [[User:Justincc|Michelle Argus]] 15 November 2012''
* The group service requires client data to send the message to each groupmember. ''Well, this is only true if you try to start sending directly to viewers. At the moment, messages are sent on to the simulator they occupy for forwarding. The data would be fetched by the same mechanisms that the simulator's currently use to distribute group IMs. [[User:Justincc|Justincc]] 03:19, 8 November 2012 (UTC)'' ''In the case of D the IM service the IMs are not sent by a simulator and communication between simulator and IM service should be kept at its absolute minimum to prevent any possible lag that could be caused simulatorside, eg. slow requests [[User:Michelle Argus|Michelle Argus]] 15 November 2012''

== E) Separate group IM relay service ==

The login status could be handled by the grid services or group service (see B and C). The group messages can optionaly be sent by the simulator or via a "relay" service which send the message to the members. The relay service receives the group member list from the central group service. The relay service can additionaly cache data

'''PROS''':

* Multiple relay service could be in use worldwide and minimize slow requests
* Requests to the group service is minimized due to cache of each relay service.
* Hosters of multiple regions can optimize their own relay service to their needs within their datacenter
* The simulator does not need to send messages and saves resources on the simulator side(optional).
* Each relay can offer filters for spam and illigal activity which meet local laws.
* POC for other services such as assets, presence, inventory, friendslist and many more.

'''CONS''':

* The relay service requires client data to send the message to each groupmember
* Requires trustworthy relay hoster.

NB: The simulator could automaticaly receive the settings of the nearest trusted relay station from the grid service on simulator startup to minimize request to the central group service.

= Status =

The alternative approach B) is present in OpenSimulator git master as of git master 1937e5f on 2012-10-20. It can be enabled by setting

<pre>
[Groups]
MessageOnlineUsersOnly = true
</pre>

in OpenSim.ini (all the other groups config params need to be set and configured correctly). More details on the parameter are in the [Groups] section of OpenSimDefaults.ini. This is currently considered experimental and defaults to false.

= References =

[1] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011421.html

[2] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011431.html

[3] https://github.com/MAReantals/opensim

[4] https://github.com/MAReantals/flotsam

[5] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011434.html

Feature Proposals/Improve Groups Service

2012-11-15T17:58:58Z

Michelle Argus: /* D) Groups service distributes IM */

=Date=

October 2012

= Status =

In progress

= Proposers =

* Michelle Argus
* Justin Clark-Casey (justincc)

= Introduction =

This may encompass many improvements to groups, but the first is to cache login information in groups to improve group IM, such that an IM isn't sent to every single user, even those offline.

= A) Proposal - Simulator tells group service about user login/logout =

Please see mailing-list e-mails [1], [2] and [5]. The changes for OpenSimulator and XmlRpcGroups are in [3] and [4].

These changes send login status information and time to the groups service from the simulator. This allows an extra 'offline' parameter to be passed to GetGroupMembers to control whether all or only online members of a group are returned.

'''PROS''':

* Only a single network call (which may be cached for a period) required on each group IM.
* Reasonably simple.
* May allow messaging across multiple OpenSimulator installations.

'''CONS''':

* Extra calls to groups service on each login/logout.
* Groups service has to cache extra information.
* Cached information not reuseable by other services.
* Accuracy of login status is dependant on groupsettings of each simulator within a grid (multiple groups possible in open grids like OSGrid).

= Alternatives =

== B) Simulator queries presence service on IM ==

One alternative is for the simulator to fetch group information and then query which group members are online when an IM is sent to a group.

'''This is current implemented as an experimental option (see status section below).'''

'''PROS''':

* Groups service doesn't need to handle online status.
* One source of online status truth that cannot become inconsistent with information cached in the groups service.
* Other services can also use the same simulator-side group users online caching, though this may not be a big factor.
* Groups service data can be backed up without any possible worries about inconsistent online status if it needs to be restored.

'''CONS''':

* Every group IM still requires an extra network call to GridUser services via the simulator, though this would be mitigated by short-term caching.
* Comparatively complex.
* If code external to OpenSimulator wanted to know online users for a group, it would have to call Presence service (and possibly cache information) itself rather than just being able to query the groups service.
* Inconsistency between presence service and groups service online information may not be important - possibly the worst that could happen is some users do not receive group members until they relog.

== C) Groups services queries presence service on members online request ==

Similar to Alternative B, the group service requests the login status of the members from the gridservices instead of the simulator. Like the original proposal, this requires modifications to the groups service interface to add a "request users online only" bool.

'''PROS''':

* Simulator doesn't need to handle online status.
* One source of online status truth that cannot become inconsistent with information cached in the groups service.
* Groups service data can be backed up without any possible worries about inconsistent online status if it needs to be restored.
* Fast data connection between grid and group server
* All group related services can use the login data

'''CONS''':

* Every group IM still requires an extra network call to GridUser services via the group service, though the results could be cached for a short period of time (e.g. 20 seconds).
* Comparatively complex.
* Inconsistency between presence service and groups service online information may not be important - possibly the worst that could happen is some users do not receive group members until they relog.

== D) Groups service distributes IM ==

Instead of distributing the message itself, the simulator passes the group IM data on to the groups service. The groups service handles message distribution to group members.

The login status could be handled by the simulator, grid services or group service (see A, B and C).

'''PROS''':

* Central service, which makes for easier management.
* Only one request is sent to the group service - ''How is this a pro? We are already sending only one request to the groups service on each IM with the other options [[User:Justincc|Justincc]] 03:14, 8 November 2012 (UTC)'' ''The Simulator request currently requests the members, then it requests online status and then it sends the IMs. We currently have atleast 3 request. If the IM is passed on, then the simulator makes only 1 request, while the IM service handles the other requests [[User:Justincc|Michelle Argus]] 15 November 2012''
* Message sending load is removed from the simulator.
* The group server can be ajusted better as its sole purpose is to manage the grouprelated work ''Could you elaborate? [[User:Justincc|Justincc]] 03:15, 8 November 2012 (UTC)'' ''A Simulator has to deal with many things eg. physics, scriptengine etc and thus the server has a more general setup sothat everything works. The less funktions a simulator has to run, the better one can fine tune the server setup for each of those funktion. Same also aplies for a IM service[[User:Justincc|Michelle Argus]]''
* Spam and illegal activity can be filtered gridwide.

'''CONS''':

* Load on the group service is significantly increased as the load of group IM sending is now concentrated at the service rather than distributed among simulators.
* Laws governing data protection and data security could be abused by grid management. ''Not sure this is a strong reason, as this could already be captured at simulator level. However, privacy concerns are worth mentioning. [[User:Justincc|Justincc]] 03:17, 8 November 2012 (UTC)'' ''In open grids the grid management has no control over what module is used/modded by the simulator hoster. [[User:Justincc|Michelle Argus]] 15 November 2012''
* The group service requires client data to send the message to each groupmember. ''Well, this is only true if you try to start sending directly to viewers. At the moment, messages are sent on to the simulator they occupy for forwarding. The data would be fetched by the same mechanisms that the simulator's currently use to distribute group IMs. [[User:Justincc|Justincc]] 03:19, 8 November 2012 (UTC)''

== E) Separate group IM relay service ==

The login status could be handled by the grid services or group service (see B and C). The group messages can optionaly be sent by the simulator or via a "relay" service which send the message to the members. The relay service receives the group member list from the central group service. The relay service can additionaly cache data

'''PROS''':

* Multiple relay service could be in use worldwide and minimize slow requests
* Requests to the group service is minimized due to cache of each relay service.
* Hosters of multiple regions can optimize their own relay service to their needs within their datacenter
* The simulator does not need to send messages and saves resources on the simulator side(optional).
* Each relay can offer filters for spam and illigal activity which meet local laws.
* POC for other services such as assets, presence, inventory, friendslist and many more.

'''CONS''':

* The relay service requires client data to send the message to each groupmember
* Requires trustworthy relay hoster.

NB: The simulator could automaticaly receive the settings of the nearest trusted relay station from the grid service on simulator startup to minimize request to the central group service.

= Status =

The alternative approach B) is present in OpenSimulator git master as of git master 1937e5f on 2012-10-20. It can be enabled by setting

<pre>
[Groups]
MessageOnlineUsersOnly = true
</pre>

in OpenSim.ini (all the other groups config params need to be set and configured correctly). More details on the parameter are in the [Groups] section of OpenSimDefaults.ini. This is currently considered experimental and defaults to false.

= References =

[1] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011421.html

[2] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011431.html

[3] https://github.com/MAReantals/opensim

[4] https://github.com/MAReantals/flotsam

[5] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011434.html

Feature Proposals/Improve Groups Service

2012-10-28T21:30:48Z

Michelle Argus: /* Proposal */

=Date=

October 2012

= Status =

In progress

= Proposers =

* Michelle Argus
* Justin Clark-Casey (justincc)

= Introduction =

This may encompass many improvements to groups, but the first is to cache login information in groups to improve group IM, such that an IM isn't sent to every single user, even those offline.

= A) Proposal =

Please see mailing-list e-mails [1], [2] and [5]. The changes for OpenSimulator and XmlRpcGroups are in [3] and [4].

These changes send login status information and time to the groups service from the simulator. This allows an extra 'offline' parameter to be passed to GetGroupMembers to control whether all or only online members of a group are returned.

'''PROS''':

* Only a single network call (which may be cached for a period) required on each group IM.
* Reasonably simple.
* May allow messaging across multiple OpenSimulator installations.

'''CONS''':

* Extra calls to groups service on each login/logout.
* Groups service has to cache extra information.
* Cached information not reuseable by other services.
* Accuracy of login status is dependant on groupsettings of each simulator within a grid (multiple groups possible in open grids like OSGrid).

== B) Alternatives ==

One alternative is for the simulator itself to call GridUserService.LoggedIn for each member of the group on each IM. However this has a very high overhead with large groups.

It may be possible to improve this by adding a new GridUserService call that accepts a list of UUIDs and only returns information for those which are logged in. However, this would need to be called for each group IM, unless this was cached for short periods of time.

'''PROS''':

* Groups service doesn't need to handle online status.
* One source of online status truth that cannot become inconsistent with information cached in the groups service.
* Other services can also use the same simulator-side group users online caching, though this may not be a big factor.
* Groups service data can be backed up without any possible worries about inconsistent online status if it needs to be restored.

'''CONS''':

* Every group IM still requires an extra network call to GridUser services via the simulator, though the results could be cached for a short period of time (e.g. 20 seconds).
* Comparatively complex.
* If code external to OpenSimulator wanted to know online users for a group, it would have to call Presence service (and possibly cache information) itself rather than just being able to query the groups service.
* Inconsistency between presence service and groups service online information may not be important - possibly the worst that could happen is some users do not receive group members until they relog.

== C) Alternatives ==

Similar to Alternative B, the group service requests the login status of the members from the gridservices instead of the simulator. The group service could cache members login status for a short time to reduce requests made.

'''PROS''':

* Simulator doesn't need to handle online status.
* One source of online status truth that cannot become inconsistent with information cached in the groups service.
* Groups service data can be backed up without any possible worries about inconsistent online status if it needs to be restored.
* Fast data connection between grid and group server
* All grouprelated services can use the login data

'''CONS''':

* Every group IM still requires an extra network call to GridUser services via the group service, though the results could be cached for a short period of time (e.g. 20 seconds).
* Comparatively complex.
* Inconsistency between presence service and groups service online information may not be important - possibly the worst that could happen is some users do not receive group members until they relog.
* Other services could reuse

== D) Alternatives ==

4. alternative is, that the simulator only passes on the group message itself to the group server. The group server then sends the IM to all online group members.

The login status could be handled by the simulator, grid services or group service (see A, B and C).

'''PROS''':

* Central service
* Only one request is sent to the group service.
* The simulator does not need to send messages and saves resources on the simulator side.
* The group server can be ajusted better as its sole purpose is to manage the grouprelated work.
* Spam and illigal activity can be filtered gridwide.

'''CONS''':

* The grid management has to maintain the group server.
* Laws governing data protection and data security could be abused by gridmanagement.
* The group service requires client data to send the message to each groupmember

== E) Alternatives ==

The login status could be handled by the grid services or group service (see B and C). The group messages can optionaly be sent by the simulator or via a "relay" service which send the message to the members. The relay service receives the group member list from the central group service. The relay service can additionaly cache data

'''PROS''':

* Multiple relay service could be in use worldwide and minimize slow requests
* Requests to the group service is minimized due to cache of each relay service.
* Hosters of multiple regions can optimize their own relay service to their needs within their datacenter
* The simulator does not need to send messages and saves resources on the simulator side(optional).
* Each relay can offer filters for spam and illigal activity which meet local laws.
* POC for other services such as assets, presence, inventory, friendslist and many more.

'''CONS''':

* The relay service requires client data to send the message to each groupmember
* Requires trustworthy relay hoster.

NB: The simulator could automaticaly receive the settings of the nearest trusted relay station from the grid service on simulator startup to minimize request to the central group service.

= Status =

The alternative approach is present in OpenSimulator git master as of git master 1937e5f on 2012-10-20. It can be enabled by setting

<pre>
[Groups]
MessageOnlineUsersOnly = true
</pre>

in OpenSim.ini (all the other groups config params need to be set and configured correctly). More details on the parameter are in the [Groups] section of OpenSimDefaults.ini. This is currently considered experimental and defaults to false.

= References =

[1] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011421.html

[2] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011431.html

[3] https://github.com/MAReantals/opensim

[4] https://github.com/MAReantals/flotsam

[5] http://lists.berlios.de/pipermail/opensim-dev/2012-October/011434.html

RemoteAdmin

2012-02-17T16:37:02Z

Michelle Argus: /* RemoteAdmin Commands */

__NOTOC__ {{Quicklinks}} 

== How to Setup the Remote Admin interface ==

First you should enable the remote admin interface to do so just add the following lines to your OpenSim.ini file Port should be set to a nonzero value to have the remote admin on a different port

As of r/16843 you can limit access to remote admin to specific IP addresses by using the optional access_ip_addresses. You can list all IP's allowed to access remote admin by seperating each IP by a comma. If access_ip_addresses isn't set, then all IP addresses can access RemoteAdmin.

[RemoteAdmin]
enabled = true
access_password = secret
enabled_methods = all

See OpenSim.ini.example in the OpenSim distribution for more details.

=== Further options ===

You can also specify a different port for the XMLRPCAdmin command listener from the default simulator HTTP port

[RemoteAdmin]
port = <port-number>

== RemoteAdmin Commands ==
<div style="background-color:#ffa0a0; padding:15px">
Caution ! All commands using parameters for the uuid of a region use "region_id" as parameter. All other parameters eg. region_uuid or regionID will be removed after June 2012
</div>

=== Agent management ===
*[[Remoteadmin:admin teleport agent|admin_teleport_agent]]

=== User management ===
*[[RemoteAdmin:admin create user|admin_create_user]]
*[[RemoteAdmin:admin create user email|admin_create_user_email]]
*[[RemoteAdmin:admin exists user|admin_exists_user]]
*[[RemoteAdmin:admin update user|admin_update_user]]

=== Object management ===

=== Parcel management ===

=== Region management ===
*[[RemoteAdmin:admin broadcast|admin_broadcast]]
*[[RemoteAdmin:admin close region|admin_close_region]]
*[[RemoteAdmin:admin create region|admin_create_region]]
*[[RemoteAdmin:admin delete region|admin_delete_region]]
*[[RemoteAdmin:admin modify region|admin_modify_region]]
*[[RemoteAdmin:admin region query|admin_region_query]]
*[[RemoteAdmin:admin restart|admin_restart]]
*[[RemoteAdmin:admin shutdown|admin_shutdown]]

=== Region file management ===
{{multicol}}
*[[RemoteAdmin:admin load heightmap|admin_load_heightmap]]
*[[RemoteAdmin:admin load oar|admin_load_oar]]
*[[RemoteAdmin:admin load xml|admin_load_xml]]
*[[RemoteAdmin:admin save heightmap|admin_save_heightmap]]
*[[RemoteAdmin:admin save oar|admin_save_oar]]
*[[RemoteAdmin:admin save xml|admin_save_xml]]

=== Region access management ===
*[[RemoteAdmin:admin acl list|admin_acl_list]]
*[[RemoteAdmin:admin acl clear|admin_acl_clear]]
*[[RemoteAdmin:admin acl add|admin_acl_add]]
*[[RemoteAdmin:admin acl remove|admin_acl_remove]]

=== Estate management ===

=== Administration ===
*[[RemoteAdmin:admin console command|admin_console_command]]

== Subcategories ==

*[[RemoteAdmin:RemoteAdmin Examples|RemoteAdmin Examples]]
*[[RemoteAdmin:RemoteAdmin Proposals|RemoteAdmin Proposals]]
*[[RemoteAdmin:RemoteAdmin Standards|RemoteAdmin Standards]]
*[[RemoteAdmin:RemoteAdmin Implement new command|RemoteAdmin How to implement new commands]]

[[Category:Development]][[Category:RemoteAdmin]]

RemoteAdmin:admin acl remove

2012-02-17T16:32:45Z

Michelle Argus: /* Optional Parameters */

'''admin_acl_remove''' remotely allows to remove a list of users from the access control list

=== Enabling admin_acl_remove ===
If not all functions are enabled, use admin_acl_remove to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_acl_remove,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Region name to add user, optionaly use region_uuid
|
|-
| ''users''
| list of users names to be removed
| eg. "Jon Doe"
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
| ''removed''
| number count of removed users
|
|}

=== Error messages ===

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_acl_remove (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'users' => 'John Doe');
$myRemoteAdmin->SendCommand('admin_acl_remove', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin acl remove

2012-02-17T16:32:30Z

Michelle Argus: /* Optional Parameters */

'''admin_acl_remove''' remotely allows to remove a list of users from the access control list

=== Enabling admin_acl_remove ===
If not all functions are enabled, use admin_acl_remove to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_acl_remove,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Region name to add user, optionaly use region_uuid
|
|-
| ''users''
| list of users names to be removed
| eg. "Jon Doe"
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_uuid''
| region id
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
| ''removed''
| number count of removed users
|
|}

=== Error messages ===

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_acl_remove (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'users' => 'John Doe');
$myRemoteAdmin->SendCommand('admin_acl_remove', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin acl clear

2012-02-17T16:32:15Z

Michelle Argus: /* Optional Parameters */

'''admin_acl_clear''' remotely allows to clear the access list for the region

=== Enabling admin_acl_clear ===
If not all functions are enabled, use admin_acl_clear to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_acl_clear,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region, optionaly region_uuid
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|}

=== Error messages ===
No error messages

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_acl_clear (multiple parameters)
$parameters = array('region_name' => 'My Plaza');
$myRemoteAdmin->SendCommand('admin_acl_clear', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin acl list

2012-02-17T16:32:04Z

Michelle Argus: /* Optional Parameters */

'''admin_acl_list''' remotely allows to retrieve a list of users who can access the region

=== Enabling admin_acl_list ===
If not all functions are enabled, use admin_acl_list to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_acl_list,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region, optionaly region_uuid
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
| ''users''
| list of users allowed access
|
|}

=== Error messages ===
No error messages

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_acl_list (multiple parameters)
$parameters = array('region_name' => 'My Plaza');
$myRemoteAdmin->SendCommand('admin_acl_list', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin save xml

2012-02-17T16:31:42Z

Michelle Argus: /* Optional Parameters */

'''admin_save_xml''' remotely allows to execute the Save XML command

=== Enabling admin_save_xml ===
If not all functions are enabled, use admin_create_region to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_save_xml,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region, optionaly region_uuid
|
|-
| ''filename''
| file name
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid, optional region_name
|
|-
| ''xml_version''
| xml_version, default 1
| 1, 2
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
|''switched''
| true when region was found
| true, false
|-
|''saved''
| true when successfully saved xml
|
|}

=== Error messages ===
No error messages

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_save_xml (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'filename' => 'my_backup.xml');
$myRemoteAdmin->SendCommand('admin_save_xml', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin save oar

2012-02-17T16:31:27Z

Michelle Argus: /* Optional Parameters */

'''admin_save_oar''' remotely allows to save a oar files of regions

=== Enabling admin_save_oar ===
If not all functions are enabled, use admin_save_oar to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_save_oar,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region, optionaly region_uuid
|
|-
| ''filename''
| file name
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid, optional region_name
|
|-
| ''noassets''
| save oar without objects
| "true"
|-
| ''profile''
| add all names of creators from this world with link to profile
| <url> of profile service
|-
| ''perm''
| objects with insufficient permissions will not be saved
| C, T, CT
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
|''saved''
| true when successfully saved xml
| true, false
|}

=== Error messages ===
No error messages

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_save_oar (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'filename' => 'my_backup.xml');
$myRemoteAdmin->SendCommand('admin_save_oar', $parameters);
?>
</source>

= See Also =

* [[Server Commands|Server Commands]]

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin save heightmap

2012-02-17T16:31:07Z

Michelle Argus: /* Optional Parameters */

'''admin_save_heightmap''' remotely allows to save a hight map of the regions to file.

=== Enabling admin_save_heightmap ===
If not all functions are enabled, use admin_save_heightmap to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_save_heightmap,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid
|
|-
| ''filename''
| save height map as file name
|
|}

=== Optional Parameters ===
These parameters are optional
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid (or region_name)
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true
|}

=== Error messages ===
When an error occures the following error value are returned

*

== Notes ==
*''accepted'' is an returned parameter, probably used prior to ''success''

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_save_heightmap (multiple parameters)
$parameters = array('regionid' => '000000-0000-0000-0000-00000000', 'filename' => 'my_terrain.raw');
$myRemoteAdmin->SendCommand('admin_save_heightmap', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin save heightmap

2012-02-17T16:30:09Z

Michelle Argus: /* Required Parameters */

'''admin_save_heightmap''' remotely allows to save a hight map of the regions to file.

=== Enabling admin_save_heightmap ===
If not all functions are enabled, use admin_save_heightmap to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_save_heightmap,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid
|
|-
| ''filename''
| save height map as file name
|
|}

=== Optional Parameters ===
No optional parameters.

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true
|}

=== Error messages ===
When an error occures the following error value are returned

*

== Notes ==
*''accepted'' is an returned parameter, probably used prior to ''success''

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_save_heightmap (multiple parameters)
$parameters = array('regionid' => '000000-0000-0000-0000-00000000', 'filename' => 'my_terrain.raw');
$myRemoteAdmin->SendCommand('admin_save_heightmap', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin load xml

2012-02-17T16:29:49Z

Michelle Argus: /* Optional Parameters */

'''admin_load_xml''' remotely allows to execute the Load XML command.

=== Enabling admin_load_xml ===
If not all functions are enabled, use admin_load_xml to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_load_xml,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region, optionaly region_uuid
|
|-
| ''filename''
| file name
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid
|
|-
| ''xml_version''
| xml_version, default 1
| 1, 2
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''loaded''
| true when successfully loaded file
| true, false
|-
|''switched''
| true when region was found
| true, false
|}

=== Error messages ===
No error messages

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_load_xml (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'filename' => 'my_xml_backup.xml');
$myRemoteAdmin->SendCommand('admin_load_xml', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin load oar

2012-02-17T16:29:33Z

Michelle Argus: /* Optional Parameters */

'''admin_load_oar''' remotely allows to load a saved OAR file into a region

=== Enabling admin_load_oar ===
If not all functions are enabled, use admin_load_oar to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_load_oar,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region, optionaly region_uuid
|
|-
| ''filename''
| file name
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid, optional region_name
|
|-
| ''merge''
| merge oar with the existing region objects
| "true"
|-
| ''skip-assets''
| skip loading assets to region objects
| "true"
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''loaded''
| true when successfully loaded file
| true, false
|}

=== Error messages ===
No error messages

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_load_oar (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'filename' => 'my_xml_backup.oar');
$myRemoteAdmin->SendCommand('admin_load_oar', $parameters);
?>
</source>

= See Also =

* [[OpenSim_Archives|How to use OpenSim Archives (OAR)]]
* [[OAR Format 0.1 | OAR Format 0.1]]
* [[OAR Format 0.2 | OAR Format 0.2]]

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin load heightmap

2012-02-17T16:28:59Z

Michelle Argus: /* Required Parameters */

'''admin_load_heightmap''' remotely allows to load a hight map files to a region.

=== Enabling admin load_heightmap ===
If not all functions are enabled, use admin_load_heightmap to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_load_heightmap,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid
|
|-
| ''filename''
| file name of terrain file
|
|}

=== Optional Parameters ===
No optional parameters.

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true
|-
|''error''
| error message when not successfull
|
|}

=== Error messages ===
When an error occures the following error value are returned

*terrain module not available

== Notes ==
*Terrain files can also be loaded via web, were the filename is the full webadress.
*''accepted'' is an returned parameter, probably used prior to ''success''

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_load_heightmap (multiple parameters)
$parameters = array('regionid' => '000000-0000-0000-0000-00000000', 'filename' => 'my_terrain.raw');
$myRemoteAdmin->SendCommand('admin_load_heightmap', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin restart

2012-02-17T16:28:28Z

Michelle Argus: /* Required Parameters */

'''admin_restart''' remotely allows to triggers a region to restart.

=== Enabling admin_restart ===
If not all functions are enabled, use admin_restart to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_restart,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid of the region
|
|}

=== Optional Parameters ===
No optional parameters

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
|''error''
| error message when not successfull
|
|-
| ''rebooting''
| true when region is restarting
|true, false
|}

=== Error messages ===
When an error occures the following error value are returned

*region not found

== Notes ==
*''accepted'' is an optional returned parameter, probably used prior to ''success''

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_restart (multiple parameters)
$parameters = array('regionID' => '000000-0000-0000-0000-00000000');
$myRemoteAdmin->SendCommand('admin_restart', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin modify region

2012-02-17T16:28:08Z

Michelle Argus: /* Returned Parameters */

'''admin_modify_region''' remotely allows to enable/disable voice and/or enable/disable public access to a region.

=== Enabling admin_modify_region ===
If not all functions are enabled, use admin_modify_region to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_modify_region,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the region
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''enable_voice''
| enable/disable voice.
| true, false
|-
| ''public",''
| enable/disable public region access.
| true, false
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
|''error''
| error message when not successfull
|
|-
| ''region_id''
| uuid of region
|
|}

=== Error messages ===
When an error occures the following error value are returned

*region \"{REGION NAME}\" does not exist
*other...

== Notes ==
*region_id not implemented... patch in work by Michelle Argus...

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_create_user (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'public' => true);
$myRemoteAdmin->SendCommand('admin_modify_region', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin delete region

2012-02-17T16:27:30Z

Michelle Argus: /* Returned Parameters */

'''admin_delete_region''' remotely allows to delete regions. All region data in the database will be removed. The region will be shutdown and removed from the map.

=== Enabling admin_delete_region ===
If not all functions are enabled, use admin_delete_region to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_delete_region,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region
|
|}

=== Optional Parameters ===
There are no optional parameters for this function

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
|''error''
| error message when not successfull
|
|-
| ''region_id''
| uuid of the region
|
|}

=== Error messages ===
When an error occures the following error value are returned

*region \"{REGION NAME}\" does not exist

== Notes ==
*If you just want to shutdown a region without removing the region from the database, use admin_close_region

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_create_user (multiple parameters)
$parameters = array('region_name' => 'My Plaza');
$myRemoteAdmin->SendCommand('admin_delete_region', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin region query

2012-01-15T11:11:25Z

Michelle Argus: /* Optional Parameters */

'''admin_region_query''' remotely allows to query the "health" of a region.

=== Enabling admin_region_query ===
If not all functions are enabled, use admin_region_query to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_region_query,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the region, optionaly use region_uuid
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_id''
| region uuid of the region.
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
|''error''
| error message when not successfull
|
|-
| ''health''
| health data of the region
|integer value
|}

=== Error messages ===
When an error occures the following error value are returned

*failed to switch to region {REGION NAME}
*failed to switch to region {REGION UUID}
*neither region_name nor region_uuid given

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_create_user (multiple parameters)
$parameters = array('region_name' => 'My Plaza');
$myRemoteAdmin->SendCommand('admin_region_query', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin

2011-12-14T01:31:58Z

Michelle Argus: /* RemoteAdmin Commands */

__NOTOC__ {{Quicklinks}} 

== How to Setup the Remote Admin interface ==

First you should enable the remote admin interface to do so just add the following lines to your OpenSim.ini file Port should be set to a nonzero value to have the remote admin on a different port

As of r/16843 you can limit access to remote admin to specific IP addresses by using the optional access_ip_addresses. You can list all IP's allowed to access remote admin by seperating each IP by a comma. If access_ip_addresses isn't set, then all IP addresses can access RemoteAdmin.

[RemoteAdmin]
enabled = true
access_password = secret
enabled_methods = all

See OpenSim.ini.example in the OpenSim distribution for more details.

=== Further options ===

You can also specify a different port for the XMLRPCAdmin command listener from the default simulator HTTP port

[RemoteAdmin]
port = <port-number>

== RemoteAdmin Commands ==

=== Agent management ===
*[[Remoteadmin:admin teleport agent|admin_teleport_agent]]

=== User management ===
*[[RemoteAdmin:admin create user|admin_create_user]]
*[[RemoteAdmin:admin create user email|admin_create_user_email]]
*[[RemoteAdmin:admin exists user|admin_exists_user]]
*[[RemoteAdmin:admin update user|admin_update_user]]

=== Object management ===

=== Parcel management ===

=== Region management ===
*[[RemoteAdmin:admin broadcast|admin_broadcast]]
*[[RemoteAdmin:admin close region|admin_close_region]]
*[[RemoteAdmin:admin create region|admin_create_region]]
*[[RemoteAdmin:admin delete region|admin_delete_region]]
*[[RemoteAdmin:admin modify region|admin_modify_region]]
*[[RemoteAdmin:admin region query|admin_region_query]]
*[[RemoteAdmin:admin restart|admin_restart]]
*[[RemoteAdmin:admin shutdown|admin_shutdown]]

=== Region file management ===
{{multicol}}
*[[RemoteAdmin:admin load heightmap|admin_load_heightmap]]
*[[RemoteAdmin:admin load oar|admin_load_oar]]
*[[RemoteAdmin:admin load xml|admin_load_xml]]
*[[RemoteAdmin:admin save heightmap|admin_save_heightmap]]
*[[RemoteAdmin:admin save oar|admin_save_oar]]
*[[RemoteAdmin:admin save xml|admin_save_xml]]

=== Region access management ===
*[[RemoteAdmin:admin acl list|admin_acl_list]]
*[[RemoteAdmin:admin acl clear|admin_acl_clear]]
*[[RemoteAdmin:admin acl add|admin_acl_add]]
*[[RemoteAdmin:admin acl remove|admin_acl_remove]]

=== Estate management ===

=== Administration ===
*[[RemoteAdmin:admin console command|admin_console_command]]

== Subcategories ==

*[[RemoteAdmin:RemoteAdmin Examples|RemoteAdmin Examples]]
*[[RemoteAdmin:RemoteAdmin Proposals|RemoteAdmin Proposals]]
*[[RemoteAdmin:RemoteAdmin Standards|RemoteAdmin Standards]]
*[[RemoteAdmin:RemoteAdmin Implement new command|RemoteAdmin How to implement new commands]]

[[Category:Development]][[Category:RemoteAdmin]]

RemoteAdmin:RemoteAdmin Standards

2011-12-14T01:28:04Z

Michelle Argus: /* common Parameters are */

__NOTOC__
{{Quicklinks}}
 

POLICY PROPOSAL:
This document is a proposal for naming standards and is not yet active.

Base Syntax: admin_Category_Function

=Naming=
Function and parameter names should use US English spelling. 

Function should be clearly named & indicative of purpose

==Parameters==
Parameters should be clearly named & use a common syntax

Eg.
use ''region_id'' and NOT region_uuid, region_ID or any other variation

===common Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''region_id'' - uuid of a region
* ''region_name'' - name of a region
* ''filename'' - name and location of a file eg. "c:/bin/my_backup.oar", "my_backup.oar", "http://www.foo.bar/my_backup.oar"
* ''agent_first_name'', ''agent_last_name'' - name of avatar
* ''agent_id'' - uuid of an avatar
* ''object_id'' - uuid of an object
* ''object_name'' - name of an object

===commonly returned Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''success'' - returns true/false when a function is executed
* ''error'' - returns the error message when an error occures

[[RemoteAdmin]]

RemoteAdmin:RemoteAdmin Implement new command

2011-12-14T01:19:36Z

Michelle Argus: /* Step 2 - Coding our new command */

{{Quicklinks}}
{{proposal}}
{{content}}

== How to implement new commands to Remote Admin ==

When implementing a new RemoteAdmin command you need to edit /OpenSim/ApplicationPlugins/RemoteController/RemoteAdminPlugin.cs

<big>'''Please see [[RemoteAdmin:RemoteAdmin_Standards|RemoteAdmin Standards]] for proposed naming schema'''</big>

Lets assume we want to create a command that outputs a line in the console containing a message and the region uuid of a region we choose.

=== Step 1 - Adding a new Command ===
First we need to define our new command and make it available. In the function ''public void Initialise(OpenSimBase openSim)'' you will find a list of all implemented commands. The available commands start with ''availableMethods...''. There we add our new command, lets call it admin_output_message.

We will now add a new availableMethods to those already listed, were admin_output_message is our command and XmlRpcOutputMessage will be the function in which our command does the work wehn called (step 2).

<source lang="csharp">

public void Initialise(OpenSimBase openSim)
{
...
//Our new command
availableMethods["admin_output_message"] = (req, ep) => InvokeXmlRpcMethod(req, ep, XmlRpcOutputMessage);
...
}
</source>

=== Step 2 - Coding our new command ===
In Step 1 we added a new command which calls the function ''XmlRpcOutputMessage''. So our next step is to create our new function and include all the goddies our command will execute.

<source lang="csharp">

private void XmlRpcOutputMessage(XmlRpcRequest request, XmlRpcResponse response, IPEndPoint remoteClient)
{
//List with all parameters that will be returned
Hashtable responseData = (Hashtable)response.Value;
//List with all parameters received
Hashtable requestData = (Hashtable)request.Params[0];

//Check if the parameter message was received
CheckStringParameters(requestData, responseData, new string[] { "message" });

Scene scene = null;
string error_message = String.Empty;
responseData["success"] = false;

//Check if a region with parameter region_id or region_name exist
CheckRegionParamsInScene(requestData, out scene, out error_message);

if (scene == null)
{
//The region is not known, so we send a error message
responseData["error"] = error_message;
throw new Exception(error_message);
}

// here we do all work when a region is found
string message = (string) requestData["message"];

m_log.InfoFormat("[RADMIN]: {0}: {1} {2}", message, scene.RegionInfo.RegionName, scene.RegionInfo.RegionID);

// We have finished our work, lets send back some information
responseData["success"] = true;
responseData["region_name"] = scene.RegionInfo.RegionName;
}
</source>

* Our new function always starts of with creating the Hashtable ''responseData'' and ''requestData''. In the ''requestData'' list we have all parameters we are recieving from our external application while ''responseData'' is the list of data we are sending back...
* If we have parameters that are needed and may not be empty, then one check these parameters using ''CheckStringParameters'' and ''CheckIntegerParams''. If any of the specified paramaters, in our case the string "message" is not given, then a error with exeption will be given and the rest of our code will not be executed.
* As we want to send region data of a given region_id or region_name we use ''CheckRegionParamsInScene''. This will output us the ''scene'' of the region if it exists. Both region_id and region_name are checked. If no region is found then scene = null and a ''error_mesage'' is returned. The error message can be used to send back as ''responseData["error"]''
* As a responce we always send ''responseData["success"]'' as true or false were true only is returned if no errors occured.
* If errors occure, we send the error message to our application as ''responseData["error"]''

[[RemoteAdmin]]

RemoteAdmin:RemoteAdmin Implement new command

2011-12-11T17:37:16Z

Michelle Argus:

{{Quicklinks}}
{{proposal}}
{{content}}

== How to implement new commands to Remote Admin ==

When implementing a new RemoteAdmin command you need to edit /OpenSim/ApplicationPlugins/RemoteController/RemoteAdminPlugin.cs

<big>'''Please see [[RemoteAdmin:RemoteAdmin_Standards|RemoteAdmin Standards]] for proposed naming schema'''</big>

Lets assume we want to create a command that outputs a line in the console containing a message and the region uuid of a region we choose.

=== Step 1 - Adding a new Command ===
First we need to define our new command and make it available. In the function ''public void Initialise(OpenSimBase openSim)'' you will find a list of all implemented commands. The available commands start with ''availableMethods...''. There we add our new command, lets call it admin_output_message.

We will now add a new availableMethods to those already listed, were admin_output_message is our command and XmlRpcOutputMessage will be the function in which our command does the work wehn called (step 2).

<source lang="csharp">

public void Initialise(OpenSimBase openSim)
{
...
//Our new command
availableMethods["admin_output_message"] = (req, ep) => InvokeXmlRpcMethod(req, ep, XmlRpcOutputMessage);
...
}
</source>

=== Step 2 - Coding our new command ===
In Step 1 we added a new command which calls the function ''XmlRpcOutputMessage''. So our next step is to create our new function and include all the goddies our command will execute.

<source lang="csharp">

private void XmlRpcOutputMessage(XmlRpcRequest request, XmlRpcResponse response, IPEndPoint remoteClient)
{
//List with all parameters that will be returned
Hashtable responseData = (Hashtable)response.Value;
//List with all parameters received
Hashtable requestData = (Hashtable)request.Params[0];

//Check if the parameter message was received
CheckStringParameters(requestData, responseData, new string[] { "message" });

Scene scene = null;
string error_message = String.Empty;
responseData["success"] = false;

//Check if a region with parameter region_id or region_name exist
SceneContainsRegion(requestData, out scene, out error_message);

if (scene == null)
{
//The region is not known, so we send a error message
responseData["error"] = error_message;
throw new Exception(error_message);
}

// here we do all work when a region is found
string message = (string) requestData["message"];

m_log.InfoFormat("[RADMIN]: {0}: {1} {2}", message, scene.RegionInfo.RegionName, scene.RegionInfo.RegionID);

// We have finished our work, lets send back some information
responseData["success"] = true;
responseData["region_name"] = scene.RegionInfo.RegionName;
}
</source>

* Our new function always starts of with creating the Hashtable ''responseData'' and ''requestData''. In the ''requestData'' list we have all parameters we are recieving from our external application while ''responseData'' is the list of data we are sending back...
* If we have parameters that are needed and may not be empty, then one check these parameters using ''CheckStringParameters'' and ''CheckIntegerParameters''. If any of the specified paramaters, in our case the string "message" is not given, then a error with exeption will be given and the rest of our code will not be executed.
* As we want to send region data of a given region_id or region_name we use ''SceneContainsRegion''. This will output us the ''scene'' of the region if it exists. Both region_id and region_name are checked. If no region is found then scene = null and a ''error_mesage'' is returned. The error message can be used to send back as ''responseData["error"]''
* As a responce we always send ''responseData["success"]'' as true or false were true only is returned if no errors occured.
* If errors occure, we send the error message to our application as ''responseData["error"]''

[[RemoteAdmin]]

RemoteAdmin:RemoteAdmin Implement new command

2011-12-11T17:36:14Z

Michelle Argus: Created page with "{{Quicklinks}} {{proposal}} {{content}} == How to implement new commands to Remote Admin == When implementing a new RemoteAdmin command you need to edit /OpenSim/ApplicationPlu..."

{{Quicklinks}}
{{proposal}}
{{content}}

== How to implement new commands to Remote Admin ==

When implementing a new RemoteAdmin command you need to edit /OpenSim/ApplicationPlugins/RemoteController/RemoteAdminPlugin.cs

<big>'''Please see [[RemoteAdmin:RemoteAdmin_Standards|RemoteAdmin Standards]] for proposed naming schema'''</big>

Lets assume we want to create a command that outputs a line in the console containing a message and the region uuid of a region we choose.

=== Step 1 - Adding a new Command ===
First we need to define our new command and make it available. In the function ''public void Initialise(OpenSimBase openSim)'' you will find a list of all implemented commands. The available commands start with ''availableMethods...''. There we add our new command, lets call it admin_output_message.

We will now add a new availableMethods to those already listed, were admin_output_message is our command and XmlRpcOutputMessage will be the function in which our command does the work wehn called (step 2).

<source lang="csharp">

public void Initialise(OpenSimBase openSim)
{
...
//Our new command
availableMethods["admin_output_message"] = (req, ep) => InvokeXmlRpcMethod(req, ep, XmlRpcOutputMessage);
...
}
</source>

=== Step 2 - Coding our new command ===
In Step 1 we added a new command which calls the function ''XmlRpcOutputMessage''. So our next step is to create our new function and include all the goddies our command will execute.

<source lang="csharp">

private void XmlRpcOutputMessage(XmlRpcRequest request, XmlRpcResponse response, IPEndPoint remoteClient)
{
//List with all parameters that will be returned
Hashtable responseData = (Hashtable)response.Value;
//List with all parameters received
Hashtable requestData = (Hashtable)request.Params[0];

//Check if the parameter message was received
CheckStringParameters(requestData, responseData, new string[] { "message" });

Scene scene = null;
string error_message = String.Empty;
responseData["success"] = false;

//Check if a region with parameter region_id or region_name exist
SceneContainsRegion(requestData, out scene, out error_message);

if (scene == null)
{
//The region is not known, so we send a error message
responseData["error"] = error_message;
throw new Exception(error_message);
}

// here we do all work when a region is found
string message = (string) requestData["message"];

m_log.InfoFormat("[RADMIN]: {0}: {1} {2}", message, scene.RegionInfo.RegionName, scene.RegionInfo.RegionID);

// We have finished our work, lets send back some information
responseData["success"] = true;
responseData["region_name"] = scene.RegionInfo.RegionName;
}
</source>

* Our new function always starts of with creating the Hashtable ''responseData'' and ''requestData''. In the ''requestData'' list we have all parameters we are recieving from our external application while ''responseData'' is the list of data we are sending back...
* If we have parameters that are needed and may not be empty, then one check these parameters using ''CheckStringParameters'' and ''CheckIntegerParameters''. If any of the specified paramaters, in our case the string "message" is not given, then a error with exeption will be given and the rest of our code will not be executed.
* As we want to send region data of a given region_id or region_name we use ''SceneContainsRegion''. This will output us the ''scene'' of the region if it exists. Both region_id and region_name are checked. If no region is found then scene = null and a ''error_mesage'' is returned. The error message can be used to send back as ''responseData["error"]''
* As a responce we always send ''responseData["success"]'' as true or false were true only is returned if no errors occured.
* If errors occure, we send the error message to our application as ''responseData["error"]''

RemoteAdmin

2011-12-11T15:45:25Z

Michelle Argus:

__NOTOC__ {{Quicklinks}} 

== How to Setup the Remote Admin interface ==

First you should enable the remote admin interface to do so just add the following lines to your OpenSim.ini file Port should be set to a nonzero value to have the remote admin on a different port

As of r/16843 you can limit access to remote admin to specific IP addresses by using the optional access_ip_addresses. You can list all IP's allowed to access remote admin by seperating each IP by a comma. If access_ip_addresses isn't set, then all IP addresses can access RemoteAdmin.

[RemoteAdmin]
enabled = true
access_password = secret
enabled_methods = all

See OpenSim.ini.example in the OpenSim distribution for more details.

=== Further options ===

You can also specify a different port for the XMLRPCAdmin command listener from the default simulator HTTP port

[RemoteAdmin]
port = <port-number>

== RemoteAdmin Commands ==

=== Agent management ===
*[[Remoteadmin:admin teleport agent|admin_teleport_agent]]

=== User management ===
*[[RemoteAdmin:admin create user|admin_create_user]]
*[[RemoteAdmin:admin create user email|admin_create_user_email]]
*[[RemoteAdmin:admin exists user|admin_exists_user]]
*[[RemoteAdmin:admin update user|admin_update_user]]

=== Region management ===
*[[RemoteAdmin:admin broadcast|admin_broadcast]]
*[[RemoteAdmin:admin close region|admin_close_region]]
*[[RemoteAdmin:admin create region|admin_create_region]]
*[[RemoteAdmin:admin delete region|admin_delete_region]]
*[[RemoteAdmin:admin modify region|admin_modify_region]]
*[[RemoteAdmin:admin region query|admin_region_query]]
*[[RemoteAdmin:admin restart|admin_restart]]
*[[RemoteAdmin:admin shutdown|admin_shutdown]]

=== Region file management ===
{{multicol}}
*[[RemoteAdmin:admin load heightmap|admin_load_heightmap]]
*[[RemoteAdmin:admin load oar|admin_load_oar]]
*[[RemoteAdmin:admin load xml|admin_load_xml]]
*[[RemoteAdmin:admin save heightmap|admin_save_heightmap]]
*[[RemoteAdmin:admin save oar|admin_save_oar]]
*[[RemoteAdmin:admin save xml|admin_save_xml]]

=== Region access management ===
*[[RemoteAdmin:admin acl list|admin_acl_list]]
*[[RemoteAdmin:admin acl clear|admin_acl_clear]]
*[[RemoteAdmin:admin acl add|admin_acl_add]]
*[[RemoteAdmin:admin acl remove|admin_acl_remove]]

=== Administration ===
*[[RemoteAdmin:admin console command|admin_console_command]]

== Subcategories ==

*[[RemoteAdmin:RemoteAdmin Examples|RemoteAdmin Examples]]
*[[RemoteAdmin:RemoteAdmin Proposals|RemoteAdmin Proposals]]
*[[RemoteAdmin:RemoteAdmin Standards|RemoteAdmin Standards]]
*[[RemoteAdmin:RemoteAdmin Implement new command|RemoteAdmin How to implement new commands]]

[[Category:Development]][[Category:RemoteAdmin]]

RemoteAdmin:RemoteAdmin Proposals

2011-12-11T13:37:43Z

Michelle Argus: /* RemoteAdmin Proposal Table */

{{Quicklinks}}
{{proposal}}
{{content}}

==Introduction==

This is a page dedicated to OpenSim's remote administration module

<big>'''Please see [[RemoteAdmin:RemoteAdmin_Standards|RemoteAdmin Standards]] for proposed naming schema'''</big>

* Please post your Function along with a brief description of what it would be for, or do and an example of it.
* Make sure it begins with admin_.
* And remember, almost anything within reason can be posted here as an idea, who knows, maybe a variation of your request can be possible.
* Consider posting your proposal to [http://opensimulator.org/mantis/ Mantis] so that we can smoothly discuss about it. After that, add the link to mantis issue in the description.

== RemoteAdmin Proposal Table ==

{| class="sortable" cellpadding="5" cellspacing="0" style="width:100%;border:1px solid #000000;border-collapse: collapse; white-space:normal;"
|- style="background-color:#99CCFF;font-size:6pt;font-weight:bold;border-bottom:1px solid;" align="center" valign="bottom"
| Function
| Description
| Example Usage
| Signed
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_teleport_all_agents
| Teleports all agents in a simulator or specifyed region to a region/position
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_save_iar
| executes the Save IAR command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_quit_region
| close region without removing region from the map.
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_load_iar
| executes the Load IAR command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_fcache_clear
| executes the fcache clear command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_get_windlight_scene
| get windlight settings
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_windlight_scene
| set windlight settings
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_windlight_scene_targeted
| set windlight settings for target agent
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_region_stats
| quary the region stats, similar to osGetRegionStats
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_log_level
| change the log level of the console, eg when problems occure
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_backup
| executes the backup command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_config_get
| executes the config get command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_export_map
| executes the export map command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_kill_uuid
| executes the kill uuid command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_reload_estate
| executes the reload estate command
|
| Michelle Argus
|}

RemoteAdmin:RemoteAdmin Proposals

2011-12-11T13:36:37Z

Michelle Argus: /* RemoteAdmin Proposal Table */

{{Quicklinks}}
{{proposal}}
{{content}}

==Introduction==

This is a page dedicated to OpenSim's remote administration module

<big>'''Please see [[RemoteAdmin:RemoteAdmin_Standards|RemoteAdmin Standards]] for proposed naming schema'''</big>

* Please post your Function along with a brief description of what it would be for, or do and an example of it.
* Make sure it begins with admin_.
* And remember, almost anything within reason can be posted here as an idea, who knows, maybe a variation of your request can be possible.
* Consider posting your proposal to [http://opensimulator.org/mantis/ Mantis] so that we can smoothly discuss about it. After that, add the link to mantis issue in the description.

== RemoteAdmin Proposal Table ==

{| class="sortable" cellpadding="5" cellspacing="0" style="width:100%;border:1px solid #000000;border-collapse: collapse; white-space:normal;"
|- style="background-color:#99CCFF;font-size:6pt;font-weight:bold;border-bottom:1px solid;" align="center" valign="bottom"
| Function
| Description
| Example Usage
| Signed
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_teleport_all_agents
| Teleports all agents in a simulator or specifyed region to a region/position
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_save_iar
| executes the Save IAR command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_quit_region
| close region without removing region from the map.
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_load_iar
| executes the Load IAR command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_fcache_clear
| executes the fcache clear command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_get_windlight_scene
| get windlight settings
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_windlight_scene
| set windlight settings
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_windlight_scene_targeted
| set windlight settings for target agent
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_region_stats
| quary the region stats, similar to osGetRegionStats
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_set_log_level
| change the log level of the console, eg when problems occure
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_backup
| executes the backup command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_config_get
| executes the config get command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_export_map
| executes the export map command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_kill_uuid
| executes the kill uuid command
|
| Michelle Argus
|- style="font-size:8pt;border-bottom:1px solid;" valign="top"
| admin_reload_estate
| executes the reload estate command
|
| Michelle Argus

| Michelle Argus
|}

RemoteAdmin:admin teleport agent

2011-12-11T13:28:36Z

Michelle Argus: /* Example in Python */

'''admin_teleport_agent''' remotely teleport an agent to a given region and/or position

=== Enabling admin_teleport_agent ===
If not all functions are enabled, use admin_create_teleport_agent to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_teleport_agent,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''region_name''
| Name of the new region
|
|-
| ''agent_id''
| agent uuid, optionaly agent_first_name and agent_last_name
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''agent_first_name''
| first name of agent
|
|-
| ''agent_last_name''
| last name of agent
|
|-
| ''pos_x''
| teleport to region position x
|
|-
| ''pos_y''
| teleport to region position y
|
|-
| ''pos_z''
| teleport to region position z
|
|-
| ''lookat_x''
| look in direction x
|
|-
| ''lookat_y''
| look in direction y
|
|-
| ''lookat_z''
| look in direction z
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
|
| true
|}

=== Error messages ===
No error messages

== Notes ==
* From commit 415b7b7 on Wed 7 Dec 2011 (OpenSim 0.7.3-dev)

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_teleport_agent (multiple parameters)
$parameters = array('region_name' => 'My Plaza', 'user_firstname' => 'John', 'user_lastname' => 'Doe', 'pos_x' => '15', 'pos_y' => '10');
$myRemoteAdmin->SendCommand('admin_teleport_agent', $parameters);
?>
</source>

=== Python ===

<source lang="python">
#!/usr/bin/python
import xmlrpclib

# XML-RPC URL (http_listener_port)
simulatorURL = "http://127.0.0.1:5000"

# instantiate server object
simulator = xmlrpclib.Server(simulatorURL)

# invoke admin_alert: requires password and message
simulator.admin_teleport_agent({'password':'secret', 'agent_first_name':'John','agent_last_name':'Doe','region_name':'My Plaza', 'pos_x':'15', 'pos_y':'10'})
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:RemoteAdmin Examples

2011-12-10T18:09:44Z

Michelle Argus: /* Credits */

Below are a view Examples on how to send commands from a remote enviroment.
== C# .NET ==

=== Example 1 - "admin_create_user" ===

This example needs the Nwc.XmlRpc library, located in your OpenSim bin folder.

<source lang="csharp">
public void CreateUser(Uri url, string adminPassword, string firstName, string lastName, string password, string email, int regionX, int regionY)
{
var address = Dns.GetHostEntry(url.DnsSafeHost).AddressList[0];
var ht = new Hashtable();
ht["password"] = adminPassword;
ht["user_firstname"] = firstName;
ht["user_lastname"] = lastName;
ht["user_password"] = password;
ht["user_email"] = email;
ht["start_region_x"] = regionX;
ht["start_region_y"] = regionY;
var parameters = new List<Hashtable> { ht };
var rpc = new XmlRpcRequest("admin_create_user", parameters);
rpc.Invoke(url.ToString());
}

[Test]
public void NativeUserRegistrationTest()
{
CreateUser(new Uri("http://yourgrid.com:9000/"), "secret", "Test2", "user2", "apassword", "email@address.com", 0, 0);
}
</source>

=== Example 2 - "admin_create_user" ===

<source lang="csharp">
//Author Ottalese complements of yoursimspot.com
//This example needs the CookComputing.XmlRpc library, this can be downloaded from http://www.xml-rpc.net/.
//Recently updated code I originally posted, this can be secured using SSL.

using System;
using System.Data;
using System.Configuration;
using System.Collections;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using CookComputing.XmlRpc;

[XmlRpcUrl("http://ServerIpAddress:9000/")]
public interface RemoteOpensim : IXmlRpcProxy
{
//Create new user
[XmlRpcMethod("admin_create_user")]
XmlRpcStruct admin_create_user(XmlRpcStruct Parameters);
}

public partial class _Default : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
}
protected void SubmitButton_Click(object sender, EventArgs e)
{
XmlRpcStruct NewUser = new XmlRpcStruct(); //Will contain return results.
XmlRpcStruct Parameters = new XmlRpcStruct();//Parameters passed.
try
{
RemoteOpensim Admin = XmlRpcProxyGen.Create<RemoteOpensim>();

Parameters.Add("password", "RemotePassword"); //Password you set in the .ini file for the RemoteAdmin
Parameters.Add("user_firstname", SomeStringWithFirstName);
Parameters.Add("user_lastname", SomeStringWithLastName);
Parameters.Add("user_password", SomePassword);
Parameters.Add("start_region_x", 0);
Parameters.Add("start_region_y", 0);
NewUser = Admin.admin_create_user(Parameters);

foreach (DictionaryEntry ReturnResults in NewUser)
{
Response.Write(ReturnResults.Key.ToString() + " : " + d.Value.ToString());//Returns if the user was added or not
}
}
catch (Exception ex)
{
Response.Write(ex.Message);
}
}
}
</source>

== Python ==

=== Example 1 - admin_broadcast ===

<source lang="python">
# Author : DrScofield
# Source : http://xyzzyxyzzy.net/2008/01/23/using-pythons-xmlrpclib-with-opensim/
# License : BSD License

#!/usr/bin/python
import xmlrpclib

# XML-RPC URL (http_listener_port)
simulatorUrl = "http://127.0.0.1:9000"

# instantiate server object
simulator = xmlrpclib.Server(simulatorUrl)

# invoke admin_alert: requires password and message
simulator.admin_broadcast({'password': 'secret', 'message': 'the answer is 42'})
</source>

== XML-RPC string ==

=== Example 1 - "create user" ===

(used with first C#.NET method above)

POST admin_create_user HTTP/1.0 Host: http://10.0.0.12:16384/ Content-type: text/xml Content-Length: 993

<?xml version="1.0"?> <methodCall>     <methodName>admin_create_user</methodName>         <params>             <param>                 <value>                     <struct>                         <member>                             <name>password</name>                             <value><string>password</string></value>                         </member>                         <member>                             <name>user_firstname</name>                             <value><string>male</string></value>                         </member>                         <member>                             <name>user_lastname</name>                             <value><string>9999</string></value>                         </member>                         <member>                             <name>user_password</name>                             <value><string>password</string></value>                         </member>                         <member>                             <name>user_email</name>                             <value><string>none@email.com</string></value>                         </member>                         <member>                             <name>start_region_x</name>                             <value><int>128</int></value>                         </member>                         <member>                             <name>start_region_y</name>                             <value><int>128</int></value>                         </member>                     </struct>                 </value>             </param>         </params>     </methodCall>

== RemoteAdmin executable for Windows ==

The RemoteAdmin executable for Windows is a command line tool based on the RemoteAdmin PHP Class.

Downloads and documentation on the [http://lab.newworldgrid.com/index.php/RemoteAdmin_Executable RemoteAdmin Executable webpage]

== PHP ==

=== Example 1 ===

This example needs the RemoteAdmin PHP Class file available [http://code.google.com/p/opensimtools/wiki/RemoteAdminPHPClass here]. <source lang="php">
<?php

// Author : Olish Newman
// Source : http://code.google.com/p/opensimtools/wiki/RemoteAdminPHPClass
// Licence : BSD License

// Including the RemoteAdmin PHP class. It can be downloaded from the link above.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_broadcast
$parameters = array('message' => 'the answer is 42');
$myRemoteAdmin->SendCommand('admin_broadcast', $parameters);

// Invoke admin_shutdown (example for use without parameters)
$myRemoteAdmin->SendCommand('admin_shutdown');

// Invoke admin_create_user (multiple parameters)
$parameters = array('user_firstname' => 'Ruth', 'user_lastname' => 'OpenSim', 'user_password' => 'MyPassword', 'start_region_x' => '1000', 'start_region_y' => '1000');
$myRemoteAdmin->SendCommand('admin_create_user', $parameters);
?>
</source>

Note: This script does not appear to work for create user because it tries to pass the start region x and y as a string when the RemoteAdmin needs a string. The class needs to be edited to pass it as a number or edit the remoteadmin source to convert the string to a unsigned int.

=== Example 2 ===

Another example in PHP5, using CURL. <source lang="php">
//This is the slightly modified RPC-class of the BSD-licensed WiXTD webportal
<?php
class RemotePC {

function __construct() {
$this->serveruri = "http://myhost";
$this->serverport ="9000";
$this->password ="foobar";
}

function call($command,$parameters) {
$parameters['password'] = $this->password;
$request = xmlrpc_encode_request($command, $parameters);
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $this->serveruri);
curl_setopt( $ch, CURLOPT_PORT, $this->serverport]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ( $ch, CURLOPT_POSTFIELDS, $request);
curl_setopt ( $ch, CURLOPT_TIMEOUT, 5);
$result = curl_exec($ch);
curl_close($ch);
return xmlrpc_decode($result);
}
}
?>
</source>

 

== Perl ==

Because the OpenSim internal web server just accepts HTTP/1.0 requests, it's worth to give a perl example. It's not a daily thing to do HTTP/1.0 within the LWP environment. You can get the '''[[Users:Thomax:perl-xmlrpc|Perl example here]]'''.

=== Credits ===

Thanks to DrScofield for the Python Script Sources : http://xyzzyxyzzy.net/2008/01/23/using-pythons-xmlrpclib-with-opensim/

[[RemoteAdmin]]

RemoteAdmin:RemoteAdmin Standards

2011-12-10T18:06:30Z

Michelle Argus:

__NOTOC__
{{Quicklinks}}
 

POLICY PROPOSAL:
This document is a proposal for naming standards and is not yet active.

Base Syntax: admin_Category_Function

=Naming=
Function and parameter names should use US English spelling. 

Function should be clearly named & indicative of purpose

==Parameters==
Parameters should be clearly named & use a common syntax

Eg.
use ''region_id'' and NOT region_uuid, region_ID or any other variation

===common Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''region_id'' - uuid of a region
* ''region_name'' - name of a region
* ''filename'' - name and location of a file eg. "c:/bin/my_backup.oar", "my_backup.oar", "http://www.foo.bar/my_backup.oar"
* ''agent_first_name'', ''agent_last_name'' - name of avatar
* ''agent_id'' - uuid of an avatar

===commonly returned Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''success'' - returns true/false when a function is executed
* ''error'' - returns the error message when an error occures

[[RemoteAdmin]]

RemoteAdmin:RemoteAdmin Standards

2011-12-10T17:59:50Z

Michelle Argus:

__NOTOC__
{{Quicklinks}}
 

POLICY PROPOSAL:
This document is a proposal for naming standards and is not yet active.

Base Syntax: admin_Category_Function

=Naming=
Function and parameter names should use US English spelling. 

Function should be clearly named & indicative of purpose

==Parameters==
Parameters should be clearly named & use a common syntax

Eg.
use ''region_id'' and NOT region_uuid, region_ID or any other variation

===common Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''region_id'' - uuid of a region
* ''region_name'' - name of a region
* ''filename'' - name and location of a file eg. "c:/bin/my_backup.oar", "my_backup.oar", "http://www.foo.bar/my_backup.oar"
* ''agent_first_name'', ''agent_last_name'' - name of avatar
* ''agent_id'' - uuid of an avatar

===commonly returned Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''success'' - returns true/false when a function is executed
* ''error'' - returns the error message when an error occures

[[[RemoteAdmin]]]

RemoteAdmin:RemoteAdmin Standards

2011-12-10T17:58:21Z

Michelle Argus:

__NOTOC__
{{Quicklinks}}
 

POLICY PROPOSAL:
This document is a proposal for naming standards and is not yet active.

Base Syntax: admin_Category_Function

=Naming=
Function and parameter names should use US English spelling. 

Function should be clearly named & indicative of purpose

==Parameters==
Parameters should be clearly named & use a common syntax

Eg.
use ''region_id'' and NOT region_uuid, region_ID or any other variation

===common Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''region_id'' - uuid of a region
* ''region_name'' - name of a region
* ''filename'' - name and location of a file eg. "c:/bin/my_backup.oar", "my_backup.oar", "http://www.foo.bar/my_backup.oar"
* ''agent_first_name'', ''agent_last_name'' - name of avatar
* ''agent_id'' - uuid of an avatar

===commonly returned Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''success'' - returns true/false when a function is executed
* ''error'' - returns the error message when an error occures

[[[[RemoteAdmin]]]

RemoteAdmin:RemoteAdmin Standards

2011-12-10T17:56:13Z

Michelle Argus:

__NOTOC__
{{Quicklinks}}
 

POLICY PROPOSAL:
This document is a proposal for naming standards and is not yet active.

Base Syntax: admin_Category_Function

=Naming=
Function and parameter names should use US English spelling. 

Function should be clearly named & indicative of purpose

==Parameters==
Parameters should be clearly named & use a common syntax

Eg.
use ''region_id'' and NOT region_uuid, region_ID or any other variation

===common Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''region_id'' - uuid of a region
* ''region_name'' - name of a region
* ''filename'' - name and location of a file eg. "c:/bin/my_backup.oar", "my_backup.oar", "http://www.foo.bar/my_backup.oar"
* ''agent_first_name'', ''agent_last_name'' - name of avatar
* ''agent_id'' - uuid of an avatar

===commonly returned Parameters are ===
Note: The following paramenters are NOT standard in older commands!

* ''success'' - returns true/false when a function is executed
* ''error'' - returns the error message when an error occures

[[RemoteAdmin]]

RemoteAdmin:admin create user

2011-12-10T17:47:30Z

Michelle Argus:

'''admin_create_user''' remotely allows to create a new user

=== Enabling admin_create_user ===
If not all functions are enabled, use admin_create_user to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_create_user,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''user_firstname''
| first name of user
|
|-
| ''user_lastname''
| last name of user
|
|-
| ''user_password''
| password of user
|
|-
| ''start_region_x''
| start region x position in grid
|
|-
| ''start_region_y''
| start region y position in grid
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''user_email''
| email adress of user
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
|''avatar_uuid''
| new avatar uuid, zero uuid when error occured
|
|}

=== Error messages ===
''avatar_uuid'' returnes zero uuid when an error occures

== Notes ==
*This function is only available to Robust
*This function is the same Identical to admin_create_user_email.

== Example ==
=== C# .NET ===

This example needs the Nwc.XmlRpc library, located in your OpenSim bin folder.

<source lang="csharp">
public void CreateUser(Uri url, string adminPassword, string firstName, string lastName, string password, string email, int regionX, int regionY)
{
var address = Dns.GetHostEntry(url.DnsSafeHost).AddressList[0];
var ht = new Hashtable();
ht["password"] = adminPassword;
ht["user_firstname"] = firstName;
ht["user_lastname"] = lastName;
ht["user_password"] = password;
ht["user_email"] = email;
ht["start_region_x"] = regionX;
ht["start_region_y"] = regionY;
var parameters = new List<Hashtable> { ht };
var rpc = new XmlRpcRequest("admin_create_user", parameters);
rpc.Invoke(url.ToString());
}

[Test]
public void NativeUserRegistrationTest()
{
CreateUser(new Uri("http://yourgrid.com:9000/"), "secret", "Test2", "user2", "apassword", "email@address.com", 0, 0);
}
</source>

=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_create_user (multiple parameters)
$parameters = array('user_firstname' => 'John', 'user_lastname' => 'Doe', 'user_password' => 'secret', 'start_region_x' => 10000, 'start_region_y' => 10000);
$myRemoteAdmin->SendCommand('admin_create_user', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin create user email

2011-12-10T17:46:55Z

Michelle Argus:

'''admin_create_user_email''' remotely allows to create a new user (alias for [[Remoteadmin:admin create user|admin_create_user]])

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin exists user

2011-12-10T17:46:34Z

Michelle Argus:

'''admin_exists_user''' remotely allows to check if a certain user account exists

=== Enabling admin_exists_user ===
If not all functions are enabled, use admin_exists_user to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_exists_user,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''user_firstname''
| first name of user
|
|-
| ''user_lastname''
| last name of user
|
|}

=== Optional Parameters ===
No optional parameters.

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
| ''user_firstname''
| first name of user
|
|-
| ''user_lastname''
| last name of user
|
|-
|''lastlogin''
| timestamp of last user login
|
|}

=== Error messages ===
No error messages.

== Notes ==

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_exists_user (multiple parameters)
$parameters = array('user_firstname' => 'John', 'user_lastname' => 'Doe');
$myRemoteAdmin->SendCommand('admin_exists_user', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]

RemoteAdmin:admin update user

2011-12-10T17:46:04Z

Michelle Argus:

'''admin_update_user''' remotely allows to update the password and start region of users

=== Enabling admin_update_user ===
If not all functions are enabled, use admin_update_user to enable the function in the [RemoteAdmin] section
<source lang="csharp">
enabled_methods = admin_update_user,...
</source>

== Parameters ==
=== Required Parameters ===
These parameters are required
{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''user_firstname''
| first name of user
|
|-
| ''user_lastname''
| last name of user
|
|}

=== Optional Parameters ===
These parameters are optional and do not need to be set

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''user_password''
| password of user
|
|-
| ''start_region_x''
| start region x position in grid, ''start_region_y'' required
|
|-
| ''start_region_y''
| start region y position in grid, ''start_region_x'' required
|
|}

== Returned Parameters ==
=== Returned Parameters ===
These parameters are returned by Remote Admin

{| cellspacing="0" cellpadding="4" border="1"
|-
! parameter
! Description
! Values
|-
| ''success''
| true when successfull
| true, false
|-
|''avatar_uuid''
| new avatar uuid, zero uuid when error occured
|
|}

=== Error messages ===
''avatar_uuid'' returnes zero uuid when an error occures.

== Notes ==
*This function is only available to Robust

== Example ==
=== PHP ===
<source lang="php">
<?php

// Including the RemoteAdmin PHP class.
include('RemoteAdmin.php');

// Instantiate the class with parameters identical to the Python example above
$myRemoteAdmin = new RemoteAdmin('127.0.0.1', 9000, 'secret');

// Invoke admin_update_user (multiple parameters)
$parameters = array('user_firstname' => 'John', 'user_lastname' => 'Doe', 'user_password' => 'secret');
$myRemoteAdmin->SendCommand('admin_update_user', $parameters);
?>
</source>

[[RemoteAdmin]]
[[RemoteAdmin:Commands]]