Jump to: navigation, search

Difference between revisions of "Orion/Server admin guide"

(Configuring virtual host names for launching sites)
(Configuring virtual host names for launching sites)
Line 130: Line 130:
 
==== Defaults ====
 
==== Defaults ====
 
If you don't supply the <tt>orion.site.virtualHosts</tt> property, Orion will use a default setting. On Windows and Linux, the default assigns up to 16 addresses in the range 127.0.0.2 to 127.0.0.254. On Mac OS X, there are no default addresses, so you will receive an error when you attempt to start a site.
 
If you don't supply the <tt>orion.site.virtualHosts</tt> property, Orion will use a default setting. On Windows and Linux, the default assigns up to 16 addresses in the range 127.0.0.2 to 127.0.0.254. On Mac OS X, there are no default addresses, so you will receive an error when you attempt to start a site.
<!--
+
 
 
=== Examples ===
 
=== Examples ===
 
;<code>orion.site.virtualHosts=site.myhost.net</code>
 
;<code>orion.site.virtualHosts=site.myhost.net</code>
Line 140: Line 140:
 
;<code>orion.site.virtualHosts=foo.myhost.net,*.myhost.net</code>  
 
;<code>orion.site.virtualHosts=foo.myhost.net,*.myhost.net</code>  
 
:Makes 1 domain and 1 wildcard domain available. They will be allocated in the order provided. That is, <code>foo.myhost.net</code> will be assigned to the first hosted site that is launched, and subsequent launches will be assigned subdomains of <code>myhost.net</code>.
 
:Makes 1 domain and 1 wildcard domain available. They will be allocated in the order provided. That is, <code>foo.myhost.net</code> will be assigned to the first hosted site that is launched, and subsequent launches will be assigned subdomains of <code>myhost.net</code>.
-->
 
  
 
==== Hosting locally ====
 
==== Hosting locally ====

Revision as of 14:24, 19 May 2011

This guide contains information on managing an Orion server.

Operating the server

Starting the server

The server is started by simply invoking the "eclipse" executable (eclipse.exe on Windows, "eclipse" on Unix platforms). Starting the OSGI console by passing the "-console" argument is also recommended:

 eclipse -console

Stopping the server

To stop the server, go to the OSGi console and type "close". You can also simply kill the server process, but an orderly shutdown is always recommended to ensure all data is correctly persisted.

Configuring the server

Server configuration file

Many Orion server settings are found in the Orion server configuration file. By default this file is located in the current working directory of the Orion server process in a file called orion.conf. For example you can place this file in the root of your Orion install, then launch Orion from there. If the configuration file is not in the working directory, Orion will check the platform instance location - the location specified by the -data command line argument. By default this is a directory called "serverworkspace". Alternatively, the location of the configuration file can be specified via the system property orion.core.configFile. For example add this line to eclipse.ini:

-Dorion.core.configFile=/home/fran/orion.conf

The file is a simple text configuration file with key/value pairs delimited by '=' character. Lines starting with '#' are treated as comments and ignored

Note: For those developing Orion, the server configuration file can be specified in your Eclipse launch configuration. The launch configuration file included in the bundle org.eclipse.orion.client.core will automatically use the configuration file web-ide.conf in the same bundle.

Changing the port

By default Orion will run on port 8080. To change the port, edit the file eclipse/eclipse.ini, and change the value of the "org.eclipse.equinox.http.jetty.http.port" system property.

Safely running on port 80

Running a server on port 80 usually requires running the application as the root user. For security reasons, running the Orion server as root is not recommended. Instead, you can run a basic Apache server as root, with the following entries in the Apache virtual host configuration file:

RewriteEngine On
ProxyPreserveHost On
RewriteRule ^/(.*) http://localhost:8080/$1 [P,L]

Also, for the wildcard hosting, this is used as well (in addition to a wildcard DNS entry):

ServerName orion.eclipse.org
ServerAlias *.orion.eclipse.org

Configuring paths where users can store files

By default all files created by users are stored in the Orion "server workspace". This is the location specified by the "-data" argument when launching the server. By default this workspace is stored at eclipse/serverworkspace/. To allow users to link files in other locations to their workspace, the orion.file.allowedPaths property can be set in the server configuration file. The property value is a comma-separated list of absolute file system paths. Users will be allowed to link to and edit files in any of those locations. This line in the server configuration file will enable storing of files in /home/orion on the server, or in any sub-directory thereof.

orion.file.allowedPaths=/home/orion

Configuring project layout

By default, projects are stored in the server workspace in a flat layout at the root of the workspace directory. This layout works well for single-user or small team installs. However in a large installation with hundreds or thousands of users, you may hit limits on the number of entries that can be stored in a directory. The layout can be changed to a hierarchy tree of projects organized by user id with the following property in the server configuration file:

orion.file.layout=userTree

To use the default flat directory structure, you can either omit the property entirely, or specify:

orion.file.layout=flat

Authentication type

To configure the kind of authentication used by the server, set the orion.auth.name property in the server configuration file. For example, the following line will configure the server to use simple form-based authentication:

 orion.auth.name=FORM

Valid values for this property are:

  • FORM: Simple form-based authentication
  • Basic: Basic HTTP authentication (not secure unless running on https)
  • OpenID: Authentication only with OpenID
  • FORM+OpenID: User can select form-based authentication or OpenID authentication

Allowing users to create accounts

By default, any user is allowed to create an account. To disallow anonymous account creation, you can specify what user ids are allowed to create accounts via the orion.auth.user.creation property in the server configuration file.

 orion.auth.user.creation=admin

When this property is specified, account creation can only be performed on the user management page. This page is currently only accessible for the admin user.

Creating an admin user

No accounts are built into the Orion server by default. This avoids a vulnerability caused by well-known users and passwords that administrators neglect to change. While a small-scale server might not require an admin user at all, it is useful to create an admin account for larger-scale user management (seeing list of all users, adding/deleting users, etc). To create an admin account, add following line to the server configuration file (but please use a more creative password):

orion.auth.admin.default.password=abracadabra

This will cause an administrator account to be created as the server starts up. The admin user name is "admin" and the password will be the value specified by the configuration property. Once the admin account has been created, the configuration property is no longer required on startup (the admin password can be changed later by logging in as the administrator and going to the profile management page).

Creating and deleting users

Users can be created and deleted by logging in as admin, and visiting the user management page at "/manage-users.html". For example a server on your own machine can be managed from http://localhost:8080/manage-users.html. Click the button Orion-new-user.gif to create a new user. To delete a user, click the Orion-delete-png.png button in the "Action" column next to the user to be deleted.

You can also create a user via the Orion server API. Use curl or another utility to send a POST request to "/users". The form requires the following parameters: "login" (user login id), "password" (initial password) and "passwordConf" (confirm password).

Changing passwords

To change a user's password, go to manage-users.html. From there, click on a user to view that user's profile page. On the user profile page you can change the password, change the user's display name, etc. Each user can also change their password by selecting "Profile" from the drop-down menu in the top right corner of the Orion UI.

Enabling anonymous read access

By default, each user can only read and write projects they created. When self-hosting or in small team installations, it may be useful to enable users to access each other's projects in a read-only fashion. This can be done by setting the following property in the server configuration file:

orion.file.anonymous.read=true

Automatic git projects

There is a server configuration property to automatically create a git repository for each created project. This allows a user to stage/commit changes, compare with committed changes, etc. This repository cannot currently be synchronized with a remote replica. To enable this setting, the following property must be specified in the server configuration file:

 orion.file.defaultSCM=git

Custom page footer

Installations of Orion can use a hook for providing a custom footer at the bottom of every page. This area is useful for adding copyright notices, legal disclaimers, etc.

The HTML fragment is defined as bottomHTMLFragment in org.eclipse.orion.client.core/static/js/globalCommands.js. The div containing this fragment is assigned a class "footer" and this class is defined in ide.css

Configuring virtual host names for launching sites

In Orion M6, users can select files and folders from their workspace and launch them as a stand-alone website. For this to work, you should tell the Orion server what virtual host names will be used to host sites. This is done by setting the orion.site.virtualHosts property in the server configuration file:

orion.site.virtualHosts=*.planetorion.org

The value after the = sign is a comma-separated list of domains, such as:

  • A valid domain name (eg. foo.myhost.net), or
  • A domain including wildcards (eg. *.myhost.net), or
  • A valid IP address.

The values from the list will be allocated to hosted sites as virtual host names, so they must be aliases for the Orion server. Orion will listen to incoming requests for these hosts (based on the HTTP "Host" header), and serve up the user's files as necessary.

In a multi-user environment, you'll most likely want to supply a domain wildcard (or some externally-reachable IP address) that resolves to your server. By contrast, if you're running the Orion server for yourself on your local machine, you can simply pass a list of aliases for localhost (see Hosting locally below).

Defaults

If you don't supply the orion.site.virtualHosts property, Orion will use a default setting. On Windows and Linux, the default assigns up to 16 addresses in the range 127.0.0.2 to 127.0.0.254. On Mac OS X, there are no default addresses, so you will receive an error when you attempt to start a site.

Examples

orion.site.virtualHosts=site.myhost.net
Makes 1 host name, site.myhost.net, available for allocation as a virtual host name.

orion.site.virtualHosts=127.0.0.2,127.0.0.3
Makes the 2 IP addresses available as virtual host names. Since they happen to be loopback addresses, any hosted site assigned to them will only be reachable from the local machine. (See the Note about hosting locally).

orion.site.virtualHosts=*.myhost.net
Makes all of *.myhost.net available for allocation. Hosted sites will be assigned to subdomains, for example site1.myhost.net, site2.myhost.net, etc.

orion.site.virtualHosts=foo.myhost.net,*.myhost.net
Makes 1 domain and 1 wildcard domain available. They will be allocated in the order provided. That is, foo.myhost.net will be assigned to the first hosted site that is launched, and subsequent launches will be assigned subdomains of myhost.net.

Hosting locally

When you are the only user of your Orion server, you can just use some aliases for localhost to host on. On most platforms, any 127.x.x.x address will work, so you can do this:

orion.site.virtualHosts=127.0.0.2,127.0.0.3

The above example would give you 2 IP addresses available for virtual hosts: 127.0.0.2 and 127.0.0.3.


Note.png
Running on Mac OS X:
In OS X, the above example will not work out-of-the-box. First you'll have to manually create the aliases by running these commands in Terminal.app:
$ sudo ifconfig lo0 alias 127.0.0.2 up
$ sudo ifconfig lo0 alias 127.0.0.3 up
Then try the example. Note that if you restart your machine, you'll have to do this again.


To use a more readable hostname instead of an IP address, you can edit the hosts file on your local machine and create an entry that maps friendlyHostname to 127.0.0.1. Then include the same hostname in the server configuration property, and Orion will use it:

orion.site.virtualHosts=friendlyHostname

Ongoing server management

Wiping server data

If you are deploying a demo server of Orion, you may want to periodically wipe out all user data, but preserve account names and passwords. This is done as follows:

  • Stop the server
  • Rename serverworkspace to serverworkspace.old
  • Reinstall or reimage the server if you want to be paranoid
  • Create a new clean serverworkspace directory
  • Copy the following two directories from the old server workspace to the new one:
 .metadata\.plugins\org.eclipse.core.runtime (contains server configuration file)
 .metadata\.plugins\org.eclipse.orion.server.user.securestore (contains user account information)
  • Start the server again
#!/bin/bash
 
BASE_PATH=/home/admin
ECLIPSE_PATH=eclipse-orion-0.2M6
 
 
cd $BASE_PATH || die "Cannot access home directory"
 
kill $(ps aux | grep "[o]rg.eclipse.equinox.http.jetty.http.port=8080" | awk {'print $2'})
rm -rf $ECLIPSE_PATH/serverworkspace.old
mv $ECLIPSE_PATH/serverworkspace/ $ECLIPSE_PATH/serverworkspace.old
mkdir $ECLIPSE_PATH/serverworkspace
mkdir -p $ECLIPSE_PATH/serverworkspace/.metadata/.plugins/org.eclipse.core.runtime/
rsync -av $ECLIPSE_PATH/serverworkspace.old/.metadata/.plugins/org.eclipse.core.runtime/ $ECLIPSE_PATH/serverworkspace/.metadata/.plugins/org.eclipse.core.runtime/
rsync -av $ECLIPSE_PATH/serverworkspace.old/.metadata/.plugins/org.eclipse.orion.server.user.securestorage/ $ECLIPSE_PATH/serverworkspace/.metadata/.plugins/org.eclipse.orion.server.user.securestorage/
 
# Copy "common" workspace files from git
git clone git://git.eclipse.org/gitroot/e4/org.eclipse.orion.client.git /tmp/org.eclipse.orion.client.git
mv /tmp/org.eclipse.orion.client.git/bundles/org.eclipse.orion.client.core/ $ECLIPSE_PATH/serverworkspace/
mv /tmp/org.eclipse.orion.client.git/bundles/org.eclipse.orion.client.editor/ $ECLIPSE_PATH/serverworkspace/
rm -rf /tmp/org.eclipse.orion.client.git/
$BASE_PATH/start_orion

Automating account creation with curl

To automate account creation with curl, you need to issue one curl command to log into the Orion server and capture the returned cookie. Subsequent curl calls must include the authentication cookie, and a POST payload, to create an account.

#!/bin/bash
 
# Create accounts on Orion server
CURL=/usr/bin/curl
SERVER=localhost
 
# Log in
$CURL -c curl_cookies.txt \ # Store cookies in this file
      -d 'store=Orion'    \ # POST value: store type
      -d 'login=admin'    \ # POST value: login
      -d 'password=yourpass' http://$SERVER/login
 
# Create one account
# Loop here to create multiple accounts
$CURL -b curl_cookies.txt    \ # Use this cookies file
      -H "Orion-Version:1"   \ # Specify Orion version as an HTTP header
      -d 'login=someaccount' \ # POST value: create account called someaccount
      -d 'password=abc123'   \ # POST value: password is abc123
      http://$SERVER/users