[{ALLOW edit OWLusers}]
[{ALLOW view All}]
Open Wonderland has a unified, web-based administration tool. This administration tool lets you start and stop the Wonderland server components (darkstar server, voice bridge, shared application server), view server-related log files, monitor the performance of the server, and configure various aspects of Project Wonderland. 

[{TableOfContents}]

!!!Launching the Server Admin Console

After you have started Wonderland, you may launch the web-based administration tool by visiting the following URL in your web browser:

{{{http://<host name>:<port>/wonderland-web-front/}}}

where <host name> is the host and domain name of your server machine (e.g. localhost) and <port> is the port on which the server is registered, most often port 8080. When you visit this URL, you should see the Wonderland launch page.

[{Image width='500' src='attach/Server%20Administration%20Console%20Guide/LaunchPage.png'}]

Click on the gray "Server Admin" button to access the Open Wonderland Server Administration Console. Depending on how your Wonderland server was installed, you may need to log in to access the Console. 

[{Image width='500' src='attach/Server%20Administration%20Console%20Guide/Admin-login.png'}]

!!!Manage Server

By default, you will see the Manage Server page. 

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageServer.png'}]

You can get back to this view by clicking on the Manage Server link on the left-hand side bar. The page displays the name of the server components running (Web Administration, Darkstar, Shared Application Server, Voice Bridge), the machine on which it is running, its status (Running, Starting, Shutting Down, Not Running), and Actions you can take.

By default, this view will refresh every 15 seconds. Click the links on top of the server component table to control the refresh rate of this information.

!Starting and stopping the server components

You may start, stop, and restart each server component individually or all at once via the links present on the Manage Server page.

Next to each server component, under the Actions column:

* Click __stop__ to stop the server component (if running)
* Click __restart__ to stop and then start the server component (if running)
* Click __start__ to start the server component (if not running) 

At the bottom of the table:

* Click __Stop All__ to stop all currently running server components
* Click __Start All__ to start all server components not currently running
* Click __Restart All__ to stop and then start all currently running server components 

Note: You may not stop, start, or restart the Web server via the web-based administration tool.

!A cold start

The most effective way to return a Wonderland server to known good state is to do a ''cold start''. 

# Click on the [Connected Users|http://wiki.openwonderland.org/Edit.jsp?page=Server%20Administration%20Console%20Guide#section-Server+Administration+Console+Guide-ConnectedUsers] tab to see if any users are currently connected. If so, send them a broadcast message to alert them that the server is going down.
# Click on the Manage Worlds tab.
# Follow the [snapshot|http://wiki.openwonderland.org/Edit.jsp?page=Server%20Administration%20Console%20Guide#section-Server+Administration+Console+Guide-ManageWorldsInitialWorldsAndSnapshots] instructions below to either restore a snapshot or make one current.
# Click on Manage Server tab.
# Click "Stop All."
# Wait for all the server components to report "Not Running."
# Click on "Restart All."
# Wait for all the server components to report "Running."
# Once all servers are running, users can safely connect to the server.

!Editing the server component properties

Each server component has a collection of configuration properties that are editable via this web-based administration tool. See the [Server Properties Reference|http://wiki.openwonderland.org/Wiki.jsp?page=Server%20Properties] for more information on which properties can be changed. Here is what the configuration page for the Darkstar server looks like:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageServer-DSEdit.png'}]

To edit the properties:

# On the Manager Server page, click __edit__ in the Actions column to edit the server component properties.
# In the property sheet that appears, edit the existing properties directly in the table.
# Click "Add Property" to add a new configuration property.
# Click "Restore Defaults" to restore the previously saved property values.
# Click "Save" to save the new properties or "Cancel" to revert to the existing property values.

Note: You may not edit the Web server properties via the web-based administration tool.

!Viewing the server log files

To view the log files for each server component:

# Click __log__ under the Actions column next to each server component 

For example, the log file for the Darkstar server component looks like this:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageServer-DSLog.png'}]

!(Advanced) Running the server components on different machines

In Wonderland, you can run each server component (e.g. Darkstar server, Voice Bridge, Shared Application server) on different machines to balance load. To manage where each server component runs, click the small "(edit)" link next to the text "Server Components." This screen displays each of the server components configured for this installation; each of these server components runs locally on your machine by default.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManagerServer-EditComp.png'}]

In order to run a server component of a different machine, you will need to have the Wonderland software (either compiled from source or from the binary distribution) installed on the second machine. You will also need to run the server software differently on the second machine than you do on the primary machine.

# Copy the Wonderland.jar file (typically found beneath the dist/ directory if compiling from the source code) onto the second server machine (into any directory there).
# In the same directory that contains the Wonderland.jar file on the second machine, create a file named remote.runner.properties. This is simply the normal my.run.properties file with the following extra lines:
## wonderland.webserver.launch.class=org.jdesktop.wonderland.webserver.RunRemoteRunner
## wonderland.web.server.url=http://<address of main server>:<port>, where <port> is typically 8080. 
# Run the secondary server, with the command java -jar Wonderland.jar remote.runner.properties 

Next, you must configure your primary Wonderland server to use a server component on the secondary machine. From the Edit Server Components page, make a note of the Name and Class of the server component you wish to run remotely. For your reference, the following server components are standard:

||Name 	||Class
|Darkstar Server 	|org.jdesktop.wonderland.modules.darkstar.server.DarkstarRemoteRunnerImpl
|Voice Bridge 	|org.jdesktop.wonderland.modules.voicebridge.server.VoicebridgeRemoteRunner
|Shared Application Server 	|org.jdesktop.wonderland.modules.sasxremwin.weblib.SasProviderRemoteRunnerImpl

To configure your primary Wonderland server to use a server component on the secondary machine:

# Click remove next to the desired server component (whose Location should read localhost).
# Click Add Component.
# Using the values for Name and Class of the desired server component above, fill in the form. For Location, select the Remote radio button. Fill in the text field beneath the Remote radio button with <remove server>:<port>, where <remote server> is the name of the remote server, and <port> is typically 8080. 

For example, you Add Component screen should look like this:

[{Image width='500' src='attach/Server%20Administration%20Console%20Guide/add-server-component-crp.jpg'}]

Finally,

# Click Ok on the Add Component page
# Click Save on the Edit Components page 

Your Edit Components page should look like the following:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/remote-server-component-crp.jpg'}]

!!!Client Settings

The Client Settings page allows you to change many features of the Wonderland client. The most commonly changed initial settings are presented on the first screen.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ClientSettings.png'}]

Using these controls, you can change the default initial window size, the default "Starting Location," and the default audio mode. Advanced users can click on the "Edit Properties" button to modify any property exposed by the Wonderland API.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ClientSettings-EditProps.png'}]

Click on the "Add Property" button if you wish to change more than one property value. You will get two blank fields, one for the property name and one for the value. 

!!!Connected Users

Before you restart any Wonderland server components or restore a snapshot, it is a good idea to refer to the Connected Users page to see if there are currently any users on the server.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/ConnectedUsers.png'}]

If there are, you can send a Broadcast Message informing them that the system is about to go down. You can, of course, use Broadcast Messages to send any sort of messages to connected users. The messages will pop up in each user's Wonderland client window.

!!!Manage Apps (Shared X11 Applications)

Shared (X11) applications are native 2D applications that run either on Linux or Solaris (e.g. Firefox, Netbeans, Open Office) that can be displayed and used collaboratively in-world. The Wonderland server bundles a specialized X11 server to run these applications. As a system administrator, you must manually list all of the shared applications that users can create in the world. To view the list of currently configured shared applications, click on the Manage Apps tab in the web administration UI.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageApps.png'}]

To add a new shared (X11) application:

# Click the Add App link beneath the table.
# In the App Name field, enter the name of the application that will appear in the Object Palette in the Project Wonderland client. If left blank, the last token (following the final forward-slash) in the Command is used.
# In the Command field, enter the full path of the executable of the shared application.
# Click Ok. 

Your Add New Desktop (X11) App page should look like the following:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageApps-Add.png'}]

!!!Manage Content

The Wonderland server embeds a WebDav repository that serves content (e.g. 3D models, 2D images, PDFs, etc.) to clients. When users drag-and-drop 3D models or other content into the world, they are uploaded to the WebDav repository. This content can be viewed and managed via the Server Admin console. To view the content in the WebDav repository, click the Manage Content tab.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageContent.png'}]

The Manage Content page has three main sections:

# Directory listing for <directory>: Displays the entries in the current directory. The four top-level directories are: system, users, checksums, and modules.
# Create New Directory: Allows an administrator to create a new directory in the current directory.
# Upload File: Allows an administrator to upload a file into the current directory. 

To navigate the hierarchy of directories in WebDav:

# Click on the name of the directory, under the Name column. Continuing clicking on directory names until you navigate to the actual content. 

The user directory hierarchy is automatically created when new users log into the world and drag and drop content in the world. Each user will have an "avatars" directory, by default, and "art" and "audio" directories if they upload these type of data. Here's an example that shows the user directory for the user named "morris":

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageContent-morris.png'}]

Note that you can access uploaded files through this interface, such as being able to open the PDFs that the user has dragged-and-dropped into their Wonderland window.

Here's another example showing the "art" directory for the user "MaggieL":

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageContent-maggie-art.png'}]

You can see that she has some kmz files and a dae file in her art directory.

!Deleting existing directories or files

To delete a directory or file:

# Click on the delete link next to the desired directory or file 

NOTE: As an administrator, take great care when deleting directories and/or files, as you can affect the proper operation of the software. Specifically, never delete anything under the checksums and modules directories.

!Creating new directories

To create a new directory in the current directory:

# Under the Create New Directory section, enter the name of the new directory
# Click Create Directory 

!Uploading files

To upload a file into the current directory:

# Under the Upload File section, click the Choose File button, and select the file you wish to upload
# Click the Upload button 

!!!Manage Groups (Security)

To view the current list of security groups, click the Manage Groups link on the left-hand side bar. It should display a list the security groups. Your screen should look something like this:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageGroups.png'}]

Security groups are collections of users to which fine-grained security permissions may be assigned. Examples of fine-grained security permissions include the ability to view and edit objects in a world. Assigning specific fine-grained security permissions to security groups is done via the Wonderland client.

Each security group entry in the list has a unique name, a number of members, and actions to be taken upon the group definition.

!Editing a security group

You can edit both the name of the security group and its members via the Server Admin console.

# Click on the "edit" link under the Actions column next to the desired Security Group to edit.
# Edit the name of a member of the group, whether that member "Owns" the Security Group (and hence can make changes the group), whether to delete the member from the Security Group, or whether to add a new member to the security group.
# Click "Update group" to save your changes or "Cancel" to revert to the previous settings. 

The edit window should look something like this:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageGroups-Edit.png'}]

!Delete a security group

To delete a security group:

# Click on "delete" under the Actions column on the row of the desired Security Group to delete. Note: there is no confirmation step after you click on the "delete" link. 

!Add a security group

To add a new security group:

# Click on the "Add group" link
# Enter the desired name of the new Security Group
# Click "Edit group members" to continue to add members to the new Security Group, etc. 

The add window should look something like this:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageGroups-AddMembers.png'}]

!!!Manage Modules

To view the list of modules currently installed in Wonderland, click on the Manage Modules link on the left-hand side bar. 

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageModules-1.png'}]

It should display four sections:

# Install a New module: Provides the ability to select a module JAR file to upload and install
# Installed Modules: A table of modules currently installed, their version, descriptions, and a checkbox to mark the module for deletion
# Pending Modules: A table of modules that are waiting to be installed for some reason, typically during the next server restart or when a module it depends upon is installed
# Removed Modules: A table of modules that are waiting to be uninstalled for some reason, typically during the next server restart or when a module that requires it is uninstalled 


!Installing new modules

In Wonderland, modules are encapsulated in JAR archive files. To install a new module into Wonderland:

# Select Choose File under the Install a New Module heading and locate the module JAR archive file to install
# Click the INSTALL button
# A page will display a success or error message
# Click the Manage Modules tab once again to refresh your view of the modules 

If the module does not depend upon any other missing module, or if the module does not require any of the server components to be restarted, it should be appear under the Installed Modules heading. Otherwise, it will appear under the Pending Modules heading, as follows:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/pending-modules-crp.jpg'}]

To have this module installed, revisit the Manager Server tab and select Restart All to restart all of the server components. Once they have restarted, the module should appear under the Installed Modules section.

!Removing existing modules

To remove an existing installed module, first select the checkbox next to its entry under the Installed Selection. For example, the "shape" module has been selected to be removed.

Next, click the Remove Selected Modules button underneath the table of installed modules. If some other installed module does not depend upon the selected module, or if the module does not require any of the server components to be restarted, it should be removed from the Installed Modules heading. Otherwise, it will appear under the Removed Modules heading, as follows:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/removed-modules-crp.jpg'}]

To have this module uninstalled, revisit the Manager Server tab and select Restart All to restart all of the server components. Once they have restarted, the module should no longer appear under the Installed Modules section.

!!!Manage Users

The Manage Users page provides a mechanism for setting up, editing, and removing user accounts.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageUsers.png'}]

To add a new user, click on the "Add User" link at the bottom of the table. For each new user, you will need to fill out a form like this one:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageUsers-create.png'}]

To edit any of this information after the user account is created, click on the "edit" link in the Actions column of the Manager Users table. To delete a user, click on the "remove" link. Note that there is no delete confirmation dialog, so please take care in removing user accounts. It it not advisable to remove any of the three default user accounts (System Administrator, Darkstar Server, or Web Server).

Note that if authentication is set up on your server and you add users in this way, users who appear in the user list may not log in as "Guest" users. They must log in using the password on record. 

!Changing a user password

As an administrator, you may reset a user's password by clicking on the "edit" link in the Actions column by the user's name in the View Users table.

Users can change their own passwords by clicking on the "Server Admin" button on the Wonderland launch page. This provides them with a login screen:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-UserLogin.png'}]

Once logged in, users can administer their own personal information, including changing their password:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-UserLogin-update.png'}]

!!!Manage Worlds (initial worlds and snapshots)

To view the current list of initial worlds and world snapshots, click the Manage Words link on the left-hand side bar. It should display two lists: a list of initial worlds and a list of snapshots of worlds. Your screen should look something like this:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageWorlds-1.png'}]

Each Initial World has a name, a path, and a set of actions. Under the Actions header, initial worlds either have the "make current" action or the "Current" indicator with a "restore" link.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageWorlds-CurrentRestore.png'}]

Each Snapshot, has a name, date, description, and a set of actions. Under the Actions header, snapshots of worlds either have the "Current" label and the "restore" link, indicating that it is the basis for the initial world state, or the "make current" link. They also have "edit" and "remove" links.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageWorlds-Snapshots.png'}]

!Selecting the initial world

You may initialize the state of the world to one of the worlds listed under either the "Initial Worlds" heading or the "Snapshots" heading. The current initial world has the label "Current" under the Actions column. To set the initial state of the world:

# Click "make current" under the Actions header of the desired initial world or world snapshot
# Click OK on the Confirm page 

This will reset the state of the world to that stored in the selected world and restart the server. When clients reconnect to the server, they see a new world state.

!Restoring the world state

You may restore the state of the world to the currently-selected world. You may do this for either an Initial World or a Snapshot. You can only restore to the state of the world if it has a "Current" label under the Actions column. To restore the state of the world.

# Click "restore" under the Actions header of the desired initial world or world snapshot
# Click OK on the Confirm page 

Although it is not absolutely necessary, it is good practice to also stop and restart all the servers after you restore a snapshot. This is particularly true if you are restoring a snapshot because you encountered some problems with your client. To stop and restart the servers:

# Click on "Manage Servers" in the left navigation pane
# Under the table, click "Stop All"
# Wait until the status of all server components except for the Web Administration Server says "Stopped"
# Click on "Restart All" 

This will restore the state of the world to a known good state and restart all servers, clearing out any bad data. When clients reconnect to the server, they will see a clean world as it was saved when the snapshot was created.

!Creating a world snapshot

A Snapshot represents the current state of the running world stored on disk. You may take a Snapshot at any point (and restore to that snapshot using the steps above), although the process will restart the server and clients will have to reconnect. To create a Snapshot:

# Click the "Create snapshot" link under the Snapshots section
# Click OK on the Confirm page 

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageWorlds-3.png'}]

After the snapshot has been created the snapshot entry should look something like this:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageWorlds-SnapshotsNewlyCreated.png'}]

The initial name of the snapshot is the time and date the snapshot was performed. It is a good idea to add a description to your snapshot so you can remember what it includes. To do this:

# Click on the "edit" action.
# Type in a meaningful description.
# Click the "Save" button.

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageWorlds-SnapshotsEdit.png'}]

Your entry will now be updated to look something like this:

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-ManageWorlds-SnapshotsDescription.png'}]

To reset the state of the world to the state stored in the snapshot, follow the instructions above.

!Deleting a world snapshot

You may also delete a stored snapshot at any point:

# Click on the "remove" link under the Actions column next to the desired Snapshot to remove. Note: there is no confirmation step after you click on the "remove" link 

!Editing a world snapshot's properties

You can edit both the Snapshot name and its description.

# Click on the "edit" link under the Actions column next to the desired Snapshot to edit
# Edit either/both the name and description
# Click OK to save your changes 

!!!Monitor Server

To view statistics on the current performance of the server, click the Monitor Server link on the left-hand side bar. It should display a graph of network "ping" times, indicating the health of the Darkstar server component. (Typically values below 250 ms indicate a healthy server).

[{Image width='600' src='attach/Server%20Administration%20Console%20Guide/Admin-MonitorServer.png'}]

You may control the rate at which this information is refreshed via the links on top of the graph. The list to the right of the graph, labeled with the letters of the alphabet, indicate when the Darkstar server component has been stopped and started.



-------
''This material is distributed under the [GNU General Public License Version 2|http://www.gnu.org/licenses/gpl-2.0.html]''