RemoteAdmin

2011-11-18T18:54:46Z

Maelzel:

__NOTOC__ {{Quicklinks}} 

== How to Setup the Remote Admin ==

=== Setup OpenSim ===

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
port = 0
;access_ip_addresses = 0.0.0.0, 0.0.0.0, ...

=== Example in 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>

=== Another Example in C# .NET ===

<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>

=== Example in Python ===

<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)
gridServerURL = ‘http://127.0.0.1:9000′

# instantiate server object
gridServer = xmlrpclib.Server(gridServerURL)

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

=== Example XML-RPC string to "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]

=== Example in PHP ===

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.

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>

 

=== Example in 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]]'''.

== RemoteAdmin Commands ==

{| cellspacing="0" cellpadding="4" border="1"
|-
! Name
! Status
! Description
! Parameters
|-
| [[Remoteadmin:admin create region|admin_create_region]]
| 
| Create a new region
| region_name, region_id (optional), estate_owner_first (optional), estate_owner_last (optional), estate_owner_uuid (optional), listen_ip, listen_port (integer), external_address, region_x (integer), region_y (integer), persist (optional), estate_name (an estate owner must be specified if the estate does not already exist)
|-
| [[Remoteadmin:admin delete region|admin_delete_region]]
| 
| Delete a region
| region_name
|-
| [[Remoteadmin:admin close region|admin_close_region]]
| 
| Close a region without deleting it.
| region_name, region_id (optional)
|-
| [[Remoteadmin:admin modify region|admin_modify_region]]
| 
| Modify a region
| region_name, region_id (optional), public, enable_voice
|-
| [[Remoteadmin:admin region query|admin_region_query]]
| 
| Query the 'health' of a region
| region_uuid or region_name
|-
| [[Remoteadmin:admin shutdown|admin_shutdown]]
| 
| Shut down the simulator
| shutdown (optional, expects 'delayed'), milliseconds
|-
| [[Remoteadmin:admin broadcast|admin_broadcast]]
| 
| Send a general alert
| message
|-
| [[Remoteadmin:admin restart|admin_restart]]
| 
| Restart Region
| regionid
|-
| [[Remoteadmin:admin load heightmap|admin_load_heightmap]]
| 
| Load Height Map
| filename, regionid
|-
| [[Remoteadmin:admin save heightmap|admin_save_heightmap]]
| 
| Execute the terrain save command
| filename, regionid
|-
| [[Remoteadmin:admin create user|admin_create_user]]
| 
| Create a new user
| user_firstname, user_lastname, user_password, start_region_x, start_region_y
|-
| [[Remoteadmin:admin create user email|admin_create_user_email]]
| 
| Create a new user (alias for admin_create_user)
| user_firstname, user_lastname, user_password, start_region_x, start_region_y
|-
| [[Remoteadmin:admin exists user|admin_exists_user]]
| 
| Check whether a certain user account exists
| user_firstname, user_lastname
|-
| [[Remoteadmin:admin update user|admin_update_user]]
| 
| Update the password/home of a user account
| user_firstname, user_lastname, user_password, start_region_x, start_region_y
|-
| [[Remoteadmin:admin load xml|admin_load_xml]]
| 
| Execute the Load XML command
| filename, region_uuid (or region_name), xml_version
|-
| [[Remoteadmin:admin save xml|admin_save_xml]]
| 
| Execute the Save XML command
| filename, region_uuid (or region_name), xml_version
|-
| [[Remoteadmin:admin load oar|admin_load_oar]]
| 
| Load a saved OAR file into a region
| filename, region_uuid (or region_name), merge (optional, use "true"), skip-assets (optional, use "true) 
|-
| [[Remoteadmin:admin save oar|admin_save_oar]]
| 
| Saved an OAR file of a regions contents
| filename, region_uuid (or region_name), profile (optinal, use profile url), noassets (optional, use "true"), perm(optinal, use C, T or CT), 
|-
| [[Remoteadmin:admin acl list|admin_acl_list]]
| 
| Retrieve a list of users who can access the region
| region_uuid or region_name
|-
| [[Remoteadmin:admin acl clear|admin_acl_clear]]
| 
| Clear the access list for the region
| region_uuid or region_name
|-
| [[Remoteadmin:admin acl add|admin_acl_add]]
| 
| Add a list of users to the access control list
| region_uuid or region_name, users
|-
| [[Remoteadmin:admin acl remove|admin_acl_remove]]
| 
| Remove a list of users from the access control list
| region_uuid or region_name, users
|}

== Credits ==

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

[[Category:Development]]

OpenSimulator - User contributions [en]

RemoteAdmin