Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Orion/Server admin guide"

(File System)
 
(92 intermediate revisions by 15 users not shown)
Line 5: Line 5:
 
== Starting 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:
+
The server is started by simply invoking the "orion" executable (orion.exe on Windows, "orion" on Unix platforms). Starting the OSGI console by passing the "-console" argument is also recommended:
  
  eclipse -console
+
% orion -console
  
 
== Stopping the server ==
 
== Stopping the server ==
Line 13: Line 13:
 
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.
 
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 =
+
== Running disconnected from a shell on Unix ==
  
== Server configuration file ==
+
On a headless Linux server it is desirable to not have to keep a shell running with OSGI console. You can start an Orion server using the nohup command in this case.
  
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 <tt>orion.conf</tt>. 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 <tt>orion.core.configFile</tt>. For example add this line to eclipse.ini:
+
% nohup orion -console 4444 > orion.log &
 +
nohup: ignoring input and redirecting stderr to stdout
  
-Dorion.core.configFile=/home/fran/orion.conf
+
We have specified the log file orion.log that will capture the console output. You may look at the log to see that the server started and there are no errors.  
  
The file is a simple text configuration file with key/value pairs delimited by '=' character. Lines starting with '#' are treated as comments and ignored
+
We have also set the console to listen to port 4444. You can telnet to port 4444 to issue the close command to stop the server.
  
'''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 <tt>org.eclipse.orion.client.core</tt> will automatically use the configuration file <tt>web-ide.conf</tt> in the same bundle.
+
% telnet localhost 4444
 +
Trying 127.0.0.1...
 +
Connected to localhost.
 +
Escape character is '^]'.
 +
osgi> close
 +
Really want to stop Equinox? (y/n; default=y)  y
 +
osgi> Connection closed by foreign host.
 +
 
 +
= Configuring the server =
 +
 
 +
== Changing the server workspace ==
 +
 
 +
The Orion server requires a folder called the Orion server workspace. This is the location specified by the <tt>-data</tt> argument when launching the server. By default this workspace is stored at <tt>eclipse/serverworkspace</tt>.
 +
 
 +
To change this location you can update the default value in the <tt>eclipse/orion.ini</tt> file or provide the <tt>-data</tt> argument as mentioned above.
 +
 
 +
When users are added and these users add their projects, files and folders, they are all stored in the Orion server workspace.
  
 
== Changing the port ==
 
== 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.
+
By default Orion will run on port 8080. To change the port, edit the file <tt>orion.ini</tt>, and change the value of the "org.eclipse.equinox.http.jetty.http.port" system property.
  
 
== Safely running on port 80 ==
 
== 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:
 
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:
 
+
<source lang="apache" >
RewriteEngine On
+
RewriteEngine On
ProxyPreserveHost On
+
ProxyPreserveHost On
RewriteRule ^/(.*) http://localhost:8080/$1 [P,L]
+
RewriteRule ^/(.*) http://localhost:8080/$1 [P,L]
 +
</source>
  
 
Also, for the wildcard hosting, this is used as well (in addition to a wildcard DNS entry):
 
Also, for the wildcard hosting, this is used as well (in addition to a wildcard DNS entry):
  
ServerName orion.eclipse.org
+
<source lang="apache">
ServerAlias *.orion.eclipse.org
+
ServerName orion.eclipse.org
 +
ServerAlias *.orion.eclipse.org
 +
</source>
 +
 
 +
= Server configuration file =
 +
 
 +
Many Orion server settings are found in the Orion server configuration file. By default Orion looks for this file in the current working directory of the Orion server process in a file called <tt>orion.conf</tt>. For example you can place this file in the root of your Orion install, then launch Orion from there.
 +
 
 +
'''Note:''' On Mac OS X, if you're launching Orion by double-clicking Orion.app, the working directory is <tt>orion.app/Contents/MacOS</tt>, so you must put the orion.conf file in that directory. (To drill into orion.app, Ctrl+click it and choose "Show Package Contents".)
 +
 
 +
If the configuration file is not in the working directory, Orion will check the platform instance location folder: [[#Changing_the_server_workspace|the server workspace location]]. Alternatively, the location of the configuration file can be specified via the system property <tt>orion.core.configFile</tt>. For example add this line to orion.ini:
 +
 
 +
-Dorion.core.configFile=/home/fran/orion.conf
 +
 
 +
The file is a simple text properties 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 <tt>org.eclipse.orion.client.core</tt> will automatically use the configuration file <tt>web-ide.conf</tt> in the same bundle.
 +
 
 +
== Example server configuration file ==
 +
An example server configuration file showing the available options can be found [https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.core/web-ide.conf here]. You can copy this file to the server workspace directory, rename it to <tt>orion.conf</tt> and use it as a template.
 +
 
 +
== Configuring to run over SSL ==
 +
The Orion server can be configured to run over the secure https protocol. In order to do it you need to generate or obtain a public/private key pair and x509 certificate and set the Orion configuration as described below..
 +
 
 +
=== Creating a private/public key pair and a certificate ===
 +
Use the keytool from Java SDK:
 +
 
 +
keytool -keystore keystore -alias jetty -genkey -keyalg RSA
 +
 
 +
You will be prompted for information about the certificate and passwords for protecting the keystore and keys in it. Once it is done a file named <code>keystore</code> is created in the current working directory and you may proceed to [[#Setting the Orion configuration|Setting the Orion configuration]]
 +
 
 +
=== Getting the certificate from a known authority ===
 +
 
 +
The keys and certificate generated in the previous step are sufficient to run Orion over https however will not be trusted by the browser what will end up with a prompt on accessing Orion pages. You may request a well known certificate authority like Thawte, VISA, ValiCert, Verisign etc. to sign your key and certificate.
 +
 
 +
=== Setting the Orion configuration ===
 +
 
 +
Now set the following properties in the [[#Server_configuration_file|server configuration file]]:
 +
<source lang="properties" >
 +
jetty.https.enabled = true
 +
jetty.https.port = 8443
 +
jetty.ssl.keystore = [the keystore location]
 +
jetty.ssl.password =  [password]
 +
jetty.ssl.keypassword = [password]
 +
jetty.ssl.protocol = SSLv3
 +
</source>
 +
 
 +
== Setting the context path ==
 +
The <tt>orion.context.path</tt> property sets the ''context path'' that Orion runs under. The context path is the prefix that precedes Orion resource paths within the URL structure on your web server. If the property is not set, or is set to <tt>/</tt> (a single slash) or the empty string, Orion runs at the server root.
 +
 
 +
For example, the following context path:
 +
<source lang="properties">
 +
orion.context.path=/myide
 +
</source>
 +
… would cause the Orion editor page to be accessible at <tt>http://localhost:8080/myide/edit/edit.html</tt> and the Orion [[Orion/Server API/File API|file REST API]] to be at <tt>http://localhost:8080/myide/file</tt>.
  
 
== Configuring paths where users can store files ==
 
== Configuring paths where users can store files ==
 +
By default all files created by users are stored in the [[#Changing_the_server_workspace|Orion server workspace]]. To allow users to link files in other locations to their workspace, the <tt>orion.file.allowedPaths</tt> property can be set in the [[#Server_configuration_file|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 <tt>/home/orion</tt> on the server, or in any sub-directory thereof.
  
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 <tt>orion.file.allowedPaths</tt> property can be set in the [[#Server_configuration_file|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 <tt>/home/orion</tt> on the server, or in any sub-directory thereof.
+
<source lang="properties">
 +
orion.file.allowedPaths=/home/orion
 +
</source>
  
orion.file.allowedPaths=/home/orion
+
On Windows two backslashes must be used to separate path entries:
 +
 
 +
<source lang="properties">
 +
orion.file.allowedPaths=C:\\Users\\orion
 +
</source>
  
 
== Configuring project layout ==
 
== Configuring project layout ==
 +
If you are using the old metadata format from Orion 3.0 and earlier, or by specifying legacy:
  
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|server configuration file]]:
+
<source lang="properties">
 +
orion.core.metastore=legacy
 +
</source>
  
orion.file.layout=userTree
+
then 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|server configuration file]]:
 +
 
 +
<source lang="properties">
 +
orion.file.layout=userTree
 +
</source>
  
 
To use the default flat directory structure, you can either omit the property entirely, or specify:  
 
To use the default flat directory structure, you can either omit the property entirely, or specify:  
  
orion.file.layout=flat
+
<source lang="properties">
 +
orion.file.layout=flat
 +
</source>
 +
 
 +
The file layout property is not supported on the simple metadata storage format used by Orion 4.0 and later. The layout is always a hierarchy tree organized by user id ( see [[#Changing_the_backend_metadata_format| Changing the backend metadata format]] )
  
 
== Authentication type ==
 
== Authentication type ==
Line 62: Line 154:
 
To configure the kind of authentication used by the server, set the <tt>orion.auth.name</tt> property in the [[#Server_configuration_file|server configuration file]]. For example, the following line will configure the server to use simple form-based authentication:
 
To configure the kind of authentication used by the server, set the <tt>orion.auth.name</tt> property in the [[#Server_configuration_file|server configuration file]]. For example, the following line will configure the server to use simple form-based authentication:
  
  orion.auth.name=FORM
+
<source lang="properties">
 +
orion.auth.name=FORM+OAuth
 +
</source>
  
 
Valid values for this property are:
 
Valid values for this property are:
  
* FORM: Simple form-based authentication
+
* <code>Basic</code>: Basic HTTP authentication (not secure unless running on https)
* Basic: Basic HTTP authentication (not secure unless running on https)
+
* <code>FORM+OAuth</code>: User can select form-based authentication or OAuth authentication
* OpenID: Authentication only with OpenID
+
* FORM+OpenID: User can select form-based authentication or OpenID authentication
+
  
== Allowing users to create accounts ==
+
== Configuring OAuth authentication ==
 +
OAuth needs extra setup to work. Each OAuth client needs a client key and a client secret for each OAuth provider.
  
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 <tt>orion.auth.user.creation</tt> property in the [[#Server_configuration_file|server configuration file]].
+
=== Setting up Google OAuth authentication ===
 +
Orion supports authentication using [https://developers.google.com/accounts/docs/OAuth2Login Google's OAuth]. Google's [https://developers.google.com/accounts/docs/OAuth2Login#appsetup setup instructions] shows how to create an app on Google to get OAuth keys.Google requires the complete redirect URLs for the application. Orion's OAuth endpoints are:
  
  orion.auth.user.creation=admin
+
<code>/login/oauth</code>
  
When this property is specified, account creation can only be performed on the user management page. This page is currently only accessible for the [[#Creating_an_admin_user|admin user]].
+
<code>/mixlogin/manageoauth/oauth</code>
  
== Creating an admin user  ==
+
So to use Google's OAuth on localhost, the redirect URLs need to be:
  
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|server configuration file]] (but please use a more creative password):
+
<code>http://localhost:8080/login/oauth</code>
  
orion.auth.admin.default.password=abracadabra
+
<code>http://localhost:8080/mixlogin/manageoauth/oauth</code>
  
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).
+
Once the redirect URLs are set and the user consent screen has been configured (PRODUCT NAME and EMAIL ADDRESS must be configured) Google's authentication is ready to be used. Both the client and secret key need to be added to the configuration file <tt>orion.conf</tt>
 +
<source lang="properties">
 +
orion.oauth.google.client=client_key
 +
</source>
 +
<source lang="properties">
 +
orion.oauth.google.secret=secret_key
 +
</source>
  
== Creating and deleting users ==
+
=== Setting up GitHub OAuth authentication ===
 +
Orion also supports authentication using [https://developer.github.com/v3/oauth/ Github]. Applications using GitHub need to be [https://github.com/settings/applications/new registered] and the Authorization callback URL needs to be [https://developer.github.com/v3/oauth/#redirect-urls configured]. All redirects need to be a sub-directory of the URL set up on GitHub. So to use Orion locally just set the Homepage URL to:
  
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/profile/manage-users.html. Click the button [[Image:Orion-new-user.gif]] to create a new user. To delete a user, click the [[Image:Orion-delete-png.png]] button in the "Action" column next to the user to be deleted.
+
<code>https://localhost:8080/</code>
  
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).
+
This will automatically set the Authorization callback URL to the same value.
  
== Changing passwords ==
+
Once the application has been configured on GitHub both the client and secret key need to be added to the configuration file <tt>orion.conf</tt>
 +
<source lang="properties">
 +
orion.oauth.github.client=client_key
 +
</source>
 +
<source lang="properties">
 +
orion.oauth.github.secret=secret_key
 +
</source>
  
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.
+
== Password storage ==
 +
The Orion server stores passwords on disk using the Equinox secure storage mechanism. This storage facility is locked by a master password. You can set a master password by setting the following system property in the server's orion.ini file (please use a more creative password):
  
== Enabling anonymous read access ==
+
-Dorion.storage.password=abracadabra
  
 +
== 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|server configuration file]]:
 
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|server configuration file]]:
  
orion.file.anonymous.read=true
+
<source lang="properties">
 +
orion.file.anonymous.read=true
 +
</source>
  
== Automatic git projects ==
+
== Email configuration ==
 +
Orion allows to users to add their email account in profile, that will be later used to send email notifications, for instance resetting the password. This option is however only available if email and SMTP server configuration is present in the [[#Server_configuration_file|server configuration file]]:
  
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:
+
SMTP host that will send email:
 +
<source lang="properties">
 +
mail.smtp.host=[smtp_host]
 +
</source>
  
  orion.file.defaultSCM=git
+
Port, if different than 25 (default):
 +
<source lang="properties">
 +
mail.smtp.port=25
 +
</source>
  
== Custom page footer ==
+
Information, if authentication to SMTP server is needed:
 +
<source lang="properties">
 +
mail.smtp.auth=true
 +
</source>
  
 +
SMTP server user name, if authentication to SMTP server is needed:
 +
<source lang="properties">
 +
mail.smtp.user=[smtp_user]
 +
</source>
 +
 +
SMTP server password, if authentication to SMTP server is needed:
 +
<source lang="properties">
 +
mail.smtp.password=[password]
 +
</source>
 +
 +
Email that messages will come from (for instance webmaster@orion.eclipse.org):
 +
<source lang="properties">
 +
mail.from=[sender_of_mails]
 +
</source>
 +
 +
If authentication uses SSL/TLS there is a setting that enables the use of the STARTTLS:
 +
<source lang="properties">
 +
mail.smtp.starttls.enable=true
 +
</source>
 +
 +
Turn on trace messages of the communication with the SMTP server if debugging is needed:
 +
<source lang="properties">
 +
mail.debug=true
 +
</source>
 +
 +
== 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:
 +
<source lang="properties">
 +
orion.file.defaultSCM=git
 +
</source>
 +
 +
== 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.
 
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.
  
Line 116: Line 269:
  
 
== Configuring virtual host names for launching sites ==
 
== 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 <tt>orion.site.virtualHosts</tt> property in the [[#Server_configuration_file|server configuration file]]:
+
In Orion, users can select files and folders from their workspace and launch them as a stand-alone website. For this to work, the server administrator (you) must tell the Orion server what virtual host names the server should give out to clients. This is done by setting the <tt>orion.site.virtualHosts</tt> property in the [[#Server_configuration_file|server configuration file]]:
  
orion.site.virtualHosts='''*.planetorion.org'''
+
<source lang="properties">
 +
orion.site.virtualHosts=*.planetorion.org
 +
</source>
  
The value after the ''='' sign is a comma-separated list of domains, such as:
+
The value after the ''='' sign is a comma-separated list of domains or URL patterns. Each entry can take one of the following forms:
* A valid domain name (eg. <code>foo.myhost.net</code>), or
+
* A '''domain including wildcards'''. Example: <code>*.example.org</code>, or <code>https://*.example.org</code>.
* A domain including wildcards (eg. <code>*.myhost.net</code>), or
+
* A valid '''domain name'''. Example: <code>foo.example.org</code>.
* A valid IP address.
+
* A valid '''IP address'''. Example: <code>127.0.0.1</code>.
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.
+
The values from the list will be allocated, in the order they are listed, to hosted sites as virtual host names that clients can access. Because these values will be given out to clients, you must ensure that they are ''client-accessible aliases'' for the Orion server. The Orion server listens to incoming requests for these hosts (based on the HTTP "Host" header provided by clients), and serves up the appropriate site.
  
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 | Hosting locally]] below).
+
In a multi-user environment, you'll most likely want to supply a wildcard domain pattern that matches your [http://en.wikipedia.org/wiki/Wildcard_DNS_record wildcard DNS record], like <code>*.example.org</code> if your server is running at <code>example.org</code>. 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 | Hosting locally]] below).
  
 
==== 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 ("No more hosts available") when you attempt to start a site.
  
 
=== Examples ===
 
=== Examples ===
;<code>orion.site.virtualHosts=site.myhost.net</code>
+
'''Example 1: Subdomain.''' Makes all of <code>*.example.org</code> available for allocation. Hosted sites will be assigned to subdomains, for example <code>site1.example.org</code>, <code>site2.example.org</code>, etc. Since we haven't specified a URL scheme (http, https), Orion will give out URLs to clients by inferring the scheme and port that the server is receiving requests on. If the server is running behind a proxy, these URLs may be wrong (see Example 2 for the solution).
:Makes 1 host name, <code>site.myhost.net</code>, available for allocation as a virtual host name.<p></p>
+
<source lang="properties">orion.site.virtualHosts=*.example.org</source>
;<code>orion.site.virtualHosts=127.0.0.2,127.0.0.3</code>  
+
 
: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|Note about hosting locally]]).<p></p>
+
'''Example 2. Subdomain, server behind proxy.''' This is similar to the previous example, except that site URLs given out to clients will have the form <code>https://*.example.org</code> rather than allowing Orion to guess the scheme and port. This is important when the Orion server is running behind a reverse proxy, as the client-facing scheme/port will be different from the internal scheme/port the server is listening on.
;<code>orion.site.virtualHosts=*.myhost.net</code>
+
<source lang="properties">orion.site.virtualHosts=https://*.example.org</source>
:Makes all of <code>*.myhost.net</code> available for allocation. Hosted sites will be assigned to subdomains, for example <code>site1.myhost.net</code>, <code>site2.myhost.net</code>, etc.<p></p>
+
Or, equivalently:
;<code>orion.site.virtualHosts=foo.myhost.net,*.myhost.net</code>
+
<source lang="properties">orion.site.virtualHosts=https://*.example.org:443</source>
: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>.
+
 
 +
'''Example 3: Single domain.''' Make 1 host name, <code>site.example.org</code>, available for allocation as a virtual host name.
 +
<source lang="properties">orion.site.virtualHosts=site.example.org</source>
 +
 
 +
'''Example 4: Hosting locally.''' Make 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 [[#Hosting_locally|Hosting locally]]):
 +
<source lang="properties">orion.site.virtualHosts=127.0.0.2,127.0.0.3</source>  
 +
 
 +
'''Example 5: Mixed.''' Make 1 domain and 1 wildcard domain available. They will be allocated in the order provided. That is, <code>foo.example.org</code> will be assigned to the first hosted site that is launched, and subsequent launches will be assigned subdomains of <code>example.org</code>.
 +
<source lang="properties">orion.site.virtualHosts=foo.example.org,*.example.org</source>
  
 
=== Hosting locally ===
 
=== 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:
 
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'''
+
<source lang="properties">
 +
orion.site.virtualHosts=127.0.0.2,127.0.0.3
 +
</source>
  
 
The above example would give you 2 IP addresses available for virtual hosts: 127.0.0.2 and 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.
  
 +
To use a more readable hostname instead of an IP address, you can edit the [http://en.wikipedia.org/wiki/Hosts_file hosts file] on your local machine and create an entry that maps <code>friendlyHostname</code> to <code>127.0.0.1</code>. Then include the same hostname in the server configuration property, and Orion will use it:
  
{{Note|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:
+
<source lang="properties">
 +
orion.site.virtualHosts=friendlyHostname
 +
</source>
  
$ sudo ifconfig lo0 alias 127.0.0.2 up
+
===== Running on Mac OS X =====
$ sudo ifconfig lo0 alias 127.0.0.3 up
+
You'll have to manually create the aliases by running these commands in Terminal.app:
  
Then try the example. Note that if you restart your machine, you'll have to do this again.
+
<source lang="bash">
}}
+
$ sudo ifconfig lo0 alias 127.0.0.2 up
 +
$ sudo ifconfig lo0 alias 127.0.0.3 up
 +
</source>
  
 +
Also ensure that your orion.conf file is located properly inside the orion.app.  You will want to "Show Package Contents" in the Finder and then place the file in Contents/MacOS. Then try the example. If you restart your machine, you'll have to execute the sudo commands again.
  
To use a more readable hostname instead of an IP address, you can edit the [http://en.wikipedia.org/wiki/Hosts_file hosts file] on your local machine and create an entry that maps <code>friendlyHostname</code> to <code>127.0.0.1</code>. Then include the same hostname in the server configuration property, and Orion will use it:
+
== Changing the backend metadata format ==
 +
Older versions of the Orion server used legacy schemes for storing backend metadata (users, workspaces, and projects) on disk. The older schemes do not scale adequately for servers containing many thousands of users. When upgrading to a newer version of the Orion server that uses a different metadata scheme, ''migration'' must be performed to convert existing metadata into the new scheme.
  
orion.site.virtualHosts='''friendlyHostname'''
+
Consult the [[Orion/Metadata migration|Metadata migration]] page for a detailed explanation of legacy formats and migration.
 +
 
 +
== Configuring Orion for clustering and high availability ==
 +
Orion supports running with multiple instances of the application concurrently. However there are some steps required to configure this appropriately.
 +
 
 +
=== Authentication ===
 +
If you are relying on the web server hosting Orion to handle authentication, then you need to ensure that unique users are mapped to the same instance in order to maintain their authentication session. a front end load balancer such as nginx can be used to map unique users to consistent application instances within the cluster.
 +
 
 +
Orion does not maintain any other session state outside of authentication, so an even better approach is to handle authentication with a front end proxy, which then authenticates to the Orion instance via basic HTTP auth headers (essentially each request adds the authentication header). This approach allows you to spread the same user across multiple Orion app instances, and more importantly to failover to a new Orion instance without requiring the user to re-authenticate.
 +
=== File System ===
 +
When using multiple Orion instances, you need to ensure they are using the same underlying content storage location, so that user data is accessible and consistent across application instances. However, you don't want the two application instances to share all their state, since there is internal metadata maintained by OSGi and other libraries that are not designed for concurrent access by multiple processes. To achieve this, configure each instances to have a separate ''OSGI instance location'':
 +
 
 +
    /opt/orion/server1/workspace
 +
 
 +
Then use these configuration properties to specify a shared user data location that is common across all server instances (typically a common drive mounted on multiple machines or VMs):
 +
 
 +
    orion.file.content.location=/home/data/orion/content
 +
    orion.file.content.locking=true
 +
 
 +
The second property specifies that file-system level locks should be used to protect the data against concurrent access by separate processes. By default Orion only uses JVM-level locks that protect against concurrent thread access. Note that not all disk technologies support file-level locks used by Orion. A test script is available in the Orion server Git repository that can be used to test that your file system handles the locks properly:
 +
 
 +
    http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/bundles/org.eclipse.orion.tools.batch
 +
 
 +
== Turning on Server Logging ==
 +
 
 +
See the [[Orion/How_Tos/Turn_on_Server_Logging|Turn on Server Logging]] page for details about basic server logging.
 +
 
 +
Also see the [[Orion/How_Tos/How_to_enable_log_service_support_in_Orion|How to enable log service support in Orion]] page.
 +
 
 +
== Turning on Asynchronous Messaging ==
 +
 
 +
The Orion server is capable of publishing MQTT events to notify interested parties of notable changes to users and resources. To turn this on, you must have an MQTT broker implementation available (such as Rabbit MQ or Moquette). The Orion configuration file must specify the location, and optionally the credentials, for the message broker:
 +
 
 +
<source lang="properties">
 +
orion.events.uri=tcp://example.com/mybroker
 +
orion.events.user={username}
 +
orion.events.password={password}
 +
</source>
 +
 
 +
== Protecting against cross-site request forgery (XSRF) ==
 +
The Orion server can be configured to protect against [http://en.wikipedia.org/wiki/Cross-site_request_forgery cross-site request forgery] using a [http://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-Header_Token cookie-to-header] approach. To turn on XSRF protection, add the following line to the server's <tt>orion.conf</tt> file:
 +
 
 +
<source lang="properties">
 +
orion.XSRFPreventionFilterEnabled=true
 +
</source>
 +
 
 +
When the option is turned on, every incoming [[Orion/Server_API|API request]] must include two things:
 +
* A cookie named <tt>x-csrf-token</tt>. (The server sets this cookie equal to a nonce when the user logs in.)
 +
* A header named <tt>x-csrf-token</tt> whose value matches the cookie's value.
 +
If the cookie or the header is missing, or they do not match, a <tt>403 Forbidden</tt> response is returned. The reason for a failed XSRF check is logged to the server log.
 +
 
 +
= Administering users =
 +
== Creating and deleting users ==
 +
 
 +
Users can be created and deleted by logging in as admin, and visiting the user management page at "/profile/user-list.html". For example a server on your own machine can be managed from http://localhost:8080/profile/user-list.html. Click the button [[Image:Orion-new-user.gif|alt=New User]] to create a new user. To delete a user, click the [[Image:Orion-delete-png.png|alt=Delete user]] 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 user-list.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.
 +
 
 +
== 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 <tt>orion.auth.user.creation</tt> property in the [[#Server_configuration_file|server configuration file]].
 +
 
 +
<source lang="properties">
 +
orion.auth.user.creation=admin
 +
</source>
 +
 
 +
When this property is specified, account creation can only be performed on the user management page. This page is currently only accessible for the [[#Creating_an_admin_user|admin user]].
 +
 
 +
== Requiring users to add email while creating account ==
 +
By default, user email is optional, however this may be changed via the <tt>orion.auth.user.creation.force.email</tt> property in the [[#Server_configuration_file|server configuration file]].
 +
 
 +
<source lang="properties">
 +
orion.auth.user.creation.force.email=true
 +
</source>
 +
 
 +
When this property is specified as '''true''', users are required to provide an email address while creating the Orion account. Immediately after creating the user account an email will be sent to the provided address requesting confirmation. The account is confirmed by clicking on the generated link provided in the email. The user will be able to log in only after the given email address is confirmed. This option will only work correctly when email configuration is correctly set. See [[#Email configuration|email configuration]] section for directions.
 +
 
 +
== 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|server configuration file]] (but please use a more creative password):
 +
 
 +
<source lang="properties">
 +
orion.auth.admin.default.password=abracadabra
 +
</source>
 +
 
 +
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).
  
 
= Ongoing server management =
 
= Ongoing server management =
  
== Wiping server data ==
+
== Server Messages on Login Page ==
 +
If you wish to display a message linked to a more detailed description of some server or service information you must modify the ''server-status.json'' file located in the web directory.  By default this file contains an example which is not displayed.  The example shows that a message must contain a ''title'' (not too long), a ''startdate'' (in YYYY/MM/DD format), an ''enddate'' and a longer textual ''description'' of the message.  If the date the user connects to the server and is presented with the login page is between the startdate and enddate then the login page will show the title along with a link to a page with all the recent server messages.
  
 +
Example contents of the ''server-status.json'' file:
 +
 +
<source lang="javascript" enclose="div" line="GESHI_FANCY_LINE_NUMBERS">
 +
{
 +
"README.TXT" : "Each message needs to have a title, startdate, enddate and description field. Only the first message can be displayed on the login screen.",
 +
"messages" : [
 +
{
 +
"title" : "Provide a short description of the message here",
 +
"startdate" : "2012/10/22",
 +
"enddate" : "2012/10/23",
 +
"description" : "This is the longer description of the message.  You can see that this message will be displayed from October 22nd until the end of October 23rd."
 +
},
 +
{
 +
"title" : "This is an older message",
 +
"startdate" : "2012/10/10",
 +
"enddate" : "2012/10/12",
 +
"description" : "This message will be display on the server messages page but not in the login page."
 +
}
 +
],
 +
"example-messages" : [
 +
{
 +
"title" : "This is an older message never to be displayed",
 +
"startdate" : "2012/10/22",
 +
"enddate" : "2012/10/23",
 +
"description" : "This is the longer description of the message.  You can see that this message will be displayed from October 22nd until the end of October 23rd."
 +
}
 +
]
 +
}
 +
</source>
 +
 +
== 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:
 
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:
  
Line 174: Line 464:
 
* Copy the following two directories from the old server workspace to the new one:
 
* 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.core.runtime (contains server configuration file)
  .metadata\.plugins\org.eclipse.orion.server.user.securestore (contains user account information)
+
.metadata\.plugins\org.eclipse.orion.server.user.securestore (contains user account information)
  
 
* Start the server again
 
* Start the server again
  
<source lang="bash">
+
<source lang="bash" enclose="div" line="GESHI_FANCY_LINE_NUMBERS">
 
#!/bin/bash
 
#!/bin/bash
  
Line 196: Line 486:
 
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/
 
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
 
$BASE_PATH/start_orion
  
Line 206: Line 491:
  
 
== Automating account creation with curl ==
 
== 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.
 
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.
  
<source lang="bash">
+
<source lang="bash" enclose="div" line="GESHI_FANCY_LINE_NUMBERS">
 
#!/bin/bash
 
#!/bin/bash
  
Line 215: Line 499:
 
CURL=/usr/bin/curl
 
CURL=/usr/bin/curl
 
SERVER=localhost
 
SERVER=localhost
 +
 +
read -p "Username: " USER # Define the username
 +
read -p "Password: " PASS # Define the password
  
 
# Log in
 
# Log in
$CURL -c curl_cookies.txt \ # Store cookies in this file
+
$CURL "http://$SERVER/login/form" \
 +
      -c curl_cookies.txt \ # Store cookies in this file
 
       -d 'store=Orion'    \ # POST value: store type
 
       -d 'store=Orion'    \ # POST value: store type
 
       -d 'login=admin'    \ # POST value: login
 
       -d 'login=admin'    \ # POST value: login
       -d 'password=yourpass' http://$SERVER/login
+
       -d 'password=yourpass'
  
 
# Create one account
 
# Create one account
 
# Loop here to create multiple accounts
 
# Loop here to create multiple accounts
$CURL -b curl_cookies.txt   \ # Use this cookies file
+
$CURL "http://$SERVER/users" \
      -H "Orion-Version:1"   \ # Specify Orion version as an HTTP header
+
        -b curl_cookies.txt \ # Use this cookies file
      -d 'login=someaccount' \ # POST value: create account called someaccount
+
        -H "Orion-Version: 1" \ # Specify Orion version as an HTTP header
      -d 'password=abc123'  \ # POST value: password is abc123
+
        -d "login=$USER" \
      http://$SERVER/users
+
        -d "password=$PASS"
  
 +
#add additional line after curl request.
 +
echo ""
  
 
</source>
 
</source>
 
  
 
[[Category:Orion/How To|Server admin guide]]
 
[[Category:Orion/How To|Server admin guide]]
 
[[Category:Orion|Server admin guide]]
 
[[Category:Orion|Server admin guide]]

Latest revision as of 13:25, 21 October 2015

This guide contains information on managing an Orion server.

Contents

Operating the server

Starting the server

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

% orion -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.

Running disconnected from a shell on Unix

On a headless Linux server it is desirable to not have to keep a shell running with OSGI console. You can start an Orion server using the nohup command in this case.

% nohup orion -console 4444 > orion.log &
nohup: ignoring input and redirecting stderr to stdout

We have specified the log file orion.log that will capture the console output. You may look at the log to see that the server started and there are no errors.

We have also set the console to listen to port 4444. You can telnet to port 4444 to issue the close command to stop the server.

% telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
osgi> close
Really want to stop Equinox? (y/n; default=y)  y
osgi> Connection closed by foreign host.

Configuring the server

Changing the server workspace

The Orion server requires a folder called 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 change this location you can update the default value in the eclipse/orion.ini file or provide the -data argument as mentioned above.

When users are added and these users add their projects, files and folders, they are all stored in the Orion server workspace.

Changing the port

By default Orion will run on port 8080. To change the port, edit the file orion.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

Server configuration file

Many Orion server settings are found in the Orion server configuration file. By default Orion looks for this file 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.

Note: On Mac OS X, if you're launching Orion by double-clicking Orion.app, the working directory is orion.app/Contents/MacOS, so you must put the orion.conf file in that directory. (To drill into orion.app, Ctrl+click it and choose "Show Package Contents".)

If the configuration file is not in the working directory, Orion will check the platform instance location folder: the server workspace location. Alternatively, the location of the configuration file can be specified via the system property orion.core.configFile. For example add this line to orion.ini:

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

The file is a simple text properties 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.

Example server configuration file

An example server configuration file showing the available options can be found here. You can copy this file to the server workspace directory, rename it to orion.conf and use it as a template.

Configuring to run over SSL

The Orion server can be configured to run over the secure https protocol. In order to do it you need to generate or obtain a public/private key pair and x509 certificate and set the Orion configuration as described below..

Creating a private/public key pair and a certificate

Use the keytool from Java SDK:

keytool -keystore keystore -alias jetty -genkey -keyalg RSA

You will be prompted for information about the certificate and passwords for protecting the keystore and keys in it. Once it is done a file named keystore is created in the current working directory and you may proceed to Setting the Orion configuration

Getting the certificate from a known authority

The keys and certificate generated in the previous step are sufficient to run Orion over https however will not be trusted by the browser what will end up with a prompt on accessing Orion pages. You may request a well known certificate authority like Thawte, VISA, ValiCert, Verisign etc. to sign your key and certificate.

Setting the Orion configuration

Now set the following properties in the server configuration file:

jetty.https.enabled = true
jetty.https.port = 8443
jetty.ssl.keystore = [the keystore location]
jetty.ssl.password =  [password]
jetty.ssl.keypassword = [password]
jetty.ssl.protocol = SSLv3

Setting the context path

The orion.context.path property sets the context path that Orion runs under. The context path is the prefix that precedes Orion resource paths within the URL structure on your web server. If the property is not set, or is set to / (a single slash) or the empty string, Orion runs at the server root.

For example, the following context path:

orion.context.path=/myide

… would cause the Orion editor page to be accessible at http://localhost:8080/myide/edit/edit.html and the Orion file REST API to be at http://localhost:8080/myide/file.

Configuring paths where users can store files

By default all files created by users are stored in the Orion server workspace. 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

On Windows two backslashes must be used to separate path entries:

orion.file.allowedPaths=C:\\Users\\orion

Configuring project layout

If you are using the old metadata format from Orion 3.0 and earlier, or by specifying legacy:

orion.core.metastore=legacy

then 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

The file layout property is not supported on the simple metadata storage format used by Orion 4.0 and later. The layout is always a hierarchy tree organized by user id ( see Changing the backend metadata format )

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

Valid values for this property are:

  • Basic: Basic HTTP authentication (not secure unless running on https)
  • FORM+OAuth: User can select form-based authentication or OAuth authentication

Configuring OAuth authentication

OAuth needs extra setup to work. Each OAuth client needs a client key and a client secret for each OAuth provider.

Setting up Google OAuth authentication

Orion supports authentication using Google's OAuth. Google's setup instructions shows how to create an app on Google to get OAuth keys.Google requires the complete redirect URLs for the application. Orion's OAuth endpoints are:

/login/oauth

/mixlogin/manageoauth/oauth

So to use Google's OAuth on localhost, the redirect URLs need to be:

http://localhost:8080/login/oauth

http://localhost:8080/mixlogin/manageoauth/oauth

Once the redirect URLs are set and the user consent screen has been configured (PRODUCT NAME and EMAIL ADDRESS must be configured) Google's authentication is ready to be used. Both the client and secret key need to be added to the configuration file orion.conf

orion.oauth.google.client=client_key
orion.oauth.google.secret=secret_key

Setting up GitHub OAuth authentication

Orion also supports authentication using Github. Applications using GitHub need to be registered and the Authorization callback URL needs to be configured. All redirects need to be a sub-directory of the URL set up on GitHub. So to use Orion locally just set the Homepage URL to:

https://localhost:8080/

This will automatically set the Authorization callback URL to the same value.

Once the application has been configured on GitHub both the client and secret key need to be added to the configuration file orion.conf

orion.oauth.github.client=client_key
orion.oauth.github.secret=secret_key

Password storage

The Orion server stores passwords on disk using the Equinox secure storage mechanism. This storage facility is locked by a master password. You can set a master password by setting the following system property in the server's orion.ini file (please use a more creative password):

-Dorion.storage.password=abracadabra

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

Email configuration

Orion allows to users to add their email account in profile, that will be later used to send email notifications, for instance resetting the password. This option is however only available if email and SMTP server configuration is present in the server configuration file:

SMTP host that will send email:

 mail.smtp.host=[smtp_host]

Port, if different than 25 (default):

 mail.smtp.port=25

Information, if authentication to SMTP server is needed:

 mail.smtp.auth=true

SMTP server user name, if authentication to SMTP server is needed:

 mail.smtp.user=[smtp_user]

SMTP server password, if authentication to SMTP server is needed:

 mail.smtp.password=[password]

Email that messages will come from (for instance webmaster@orion.eclipse.org):

 mail.from=[sender_of_mails]

If authentication uses SSL/TLS there is a setting that enables the use of the STARTTLS:

 mail.smtp.starttls.enable=true

Turn on trace messages of the communication with the SMTP server if debugging is needed:

 mail.debug=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, users can select files and folders from their workspace and launch them as a stand-alone website. For this to work, the server administrator (you) must tell the Orion server what virtual host names the server should give out to clients. 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 or URL patterns. Each entry can take one of the following forms:

  • A domain including wildcards. Example: *.example.org, or https://*.example.org.
  • A valid domain name. Example: foo.example.org.
  • A valid IP address. Example: 127.0.0.1.

The values from the list will be allocated, in the order they are listed, to hosted sites as virtual host names that clients can access. Because these values will be given out to clients, you must ensure that they are client-accessible aliases for the Orion server. The Orion server listens to incoming requests for these hosts (based on the HTTP "Host" header provided by clients), and serves up the appropriate site.

In a multi-user environment, you'll most likely want to supply a wildcard domain pattern that matches your wildcard DNS record, like *.example.org if your server is running at example.org. 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 ("No more hosts available") when you attempt to start a site.

Examples

Example 1: Subdomain. Makes all of *.example.org available for allocation. Hosted sites will be assigned to subdomains, for example site1.example.org, site2.example.org, etc. Since we haven't specified a URL scheme (http, https), Orion will give out URLs to clients by inferring the scheme and port that the server is receiving requests on. If the server is running behind a proxy, these URLs may be wrong (see Example 2 for the solution).

orion.site.virtualHosts=*.example.org

Example 2. Subdomain, server behind proxy. This is similar to the previous example, except that site URLs given out to clients will have the form https://*.example.org rather than allowing Orion to guess the scheme and port. This is important when the Orion server is running behind a reverse proxy, as the client-facing scheme/port will be different from the internal scheme/port the server is listening on.

orion.site.virtualHosts=https://*.example.org

Or, equivalently:

orion.site.virtualHosts=https://*.example.org:443

Example 3: Single domain. Make 1 host name, site.example.org, available for allocation as a virtual host name.

orion.site.virtualHosts=site.example.org

Example 4: Hosting locally. Make 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 Hosting locally):

orion.site.virtualHosts=127.0.0.2,127.0.0.3

Example 5: Mixed. Make 1 domain and 1 wildcard domain available. They will be allocated in the order provided. That is, foo.example.org will be assigned to the first hosted site that is launched, and subsequent launches will be assigned subdomains of example.org.

orion.site.virtualHosts=foo.example.org,*.example.org

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.

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
Running on Mac OS X

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

Also ensure that your orion.conf file is located properly inside the orion.app. You will want to "Show Package Contents" in the Finder and then place the file in Contents/MacOS. Then try the example. If you restart your machine, you'll have to execute the sudo commands again.

Changing the backend metadata format

Older versions of the Orion server used legacy schemes for storing backend metadata (users, workspaces, and projects) on disk. The older schemes do not scale adequately for servers containing many thousands of users. When upgrading to a newer version of the Orion server that uses a different metadata scheme, migration must be performed to convert existing metadata into the new scheme.

Consult the Metadata migration page for a detailed explanation of legacy formats and migration.

Configuring Orion for clustering and high availability

Orion supports running with multiple instances of the application concurrently. However there are some steps required to configure this appropriately.

Authentication

If you are relying on the web server hosting Orion to handle authentication, then you need to ensure that unique users are mapped to the same instance in order to maintain their authentication session. a front end load balancer such as nginx can be used to map unique users to consistent application instances within the cluster.

Orion does not maintain any other session state outside of authentication, so an even better approach is to handle authentication with a front end proxy, which then authenticates to the Orion instance via basic HTTP auth headers (essentially each request adds the authentication header). This approach allows you to spread the same user across multiple Orion app instances, and more importantly to failover to a new Orion instance without requiring the user to re-authenticate.

File System

When using multiple Orion instances, you need to ensure they are using the same underlying content storage location, so that user data is accessible and consistent across application instances. However, you don't want the two application instances to share all their state, since there is internal metadata maintained by OSGi and other libraries that are not designed for concurrent access by multiple processes. To achieve this, configure each instances to have a separate OSGI instance location:

   /opt/orion/server1/workspace

Then use these configuration properties to specify a shared user data location that is common across all server instances (typically a common drive mounted on multiple machines or VMs):

   orion.file.content.location=/home/data/orion/content
   orion.file.content.locking=true

The second property specifies that file-system level locks should be used to protect the data against concurrent access by separate processes. By default Orion only uses JVM-level locks that protect against concurrent thread access. Note that not all disk technologies support file-level locks used by Orion. A test script is available in the Orion server Git repository that can be used to test that your file system handles the locks properly:

    http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/bundles/org.eclipse.orion.tools.batch

Turning on Server Logging

See the Turn on Server Logging page for details about basic server logging.

Also see the How to enable log service support in Orion page.

Turning on Asynchronous Messaging

The Orion server is capable of publishing MQTT events to notify interested parties of notable changes to users and resources. To turn this on, you must have an MQTT broker implementation available (such as Rabbit MQ or Moquette). The Orion configuration file must specify the location, and optionally the credentials, for the message broker:

orion.events.uri=tcp://example.com/mybroker
orion.events.user={username}
orion.events.password={password}

Protecting against cross-site request forgery (XSRF)

The Orion server can be configured to protect against cross-site request forgery using a cookie-to-header approach. To turn on XSRF protection, add the following line to the server's orion.conf file:

orion.XSRFPreventionFilterEnabled=true

When the option is turned on, every incoming API request must include two things:

  • A cookie named x-csrf-token. (The server sets this cookie equal to a nonce when the user logs in.)
  • A header named x-csrf-token whose value matches the cookie's value.

If the cookie or the header is missing, or they do not match, a 403 Forbidden response is returned. The reason for a failed XSRF check is logged to the server log.

Administering users

Creating and deleting users

Users can be created and deleted by logging in as admin, and visiting the user management page at "/profile/user-list.html". For example a server on your own machine can be managed from http://localhost:8080/profile/user-list.html. Click the button New User to create a new user. To delete a user, click the Delete user 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 user-list.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.

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.

Requiring users to add email while creating account

By default, user email is optional, however this may be changed via the orion.auth.user.creation.force.email property in the server configuration file.

orion.auth.user.creation.force.email=true

When this property is specified as true, users are required to provide an email address while creating the Orion account. Immediately after creating the user account an email will be sent to the provided address requesting confirmation. The account is confirmed by clicking on the generated link provided in the email. The user will be able to log in only after the given email address is confirmed. This option will only work correctly when email configuration is correctly set. See email configuration section for directions.

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

Ongoing server management

Server Messages on Login Page

If you wish to display a message linked to a more detailed description of some server or service information you must modify the server-status.json file located in the web directory. By default this file contains an example which is not displayed. The example shows that a message must contain a title (not too long), a startdate (in YYYY/MM/DD format), an enddate and a longer textual description of the message. If the date the user connects to the server and is presented with the login page is between the startdate and enddate then the login page will show the title along with a link to a page with all the recent server messages.

Example contents of the server-status.json file:

  1. {
  2. "README.TXT" : "Each message needs to have a title, startdate, enddate and description field. Only the first message can be displayed on the login screen.",
  3. "messages" : [
  4.         {
  5.                 "title" : "Provide a short description of the message here",
  6.                 "startdate" : "2012/10/22",
  7.                 "enddate" : "2012/10/23",
  8.                 "description" : "This is the longer description of the message.  You can see that this message will be displayed from October 22nd until the end of October 23rd."
  9.         },
  10.         {
  11.                 "title" : "This is an older message",
  12.                 "startdate" : "2012/10/10",
  13.                 "enddate" : "2012/10/12",
  14.                 "description" : "This message will be display on the server messages page but not in the login page."
  15.         }
  16. ],
  17. "example-messages" : [
  18.         {
  19.                 "title" : "This is an older message never to be displayed",
  20.                 "startdate" : "2012/10/22",
  21.                 "enddate" : "2012/10/23",
  22.                 "description" : "This is the longer description of the message.  You can see that this message will be displayed from October 22nd until the end of October 23rd."
  23.         }
  24. ]
  25. }

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
  1. #!/bin/bash
  2.  
  3. BASE_PATH=/home/admin
  4. ECLIPSE_PATH=eclipse-orion-0.2M6
  5.  
  6.  
  7. cd $BASE_PATH || die "Cannot access home directory"
  8.  
  9. kill $(ps aux | grep "[o]rg.eclipse.equinox.http.jetty.http.port=8080" | awk {'print $2'})
  10. rm -rf $ECLIPSE_PATH/serverworkspace.old
  11. mv $ECLIPSE_PATH/serverworkspace/ $ECLIPSE_PATH/serverworkspace.old
  12. mkdir $ECLIPSE_PATH/serverworkspace
  13. mkdir -p $ECLIPSE_PATH/serverworkspace/.metadata/.plugins/org.eclipse.core.runtime/
  14. rsync -av $ECLIPSE_PATH/serverworkspace.old/.metadata/.plugins/org.eclipse.core.runtime/ $ECLIPSE_PATH/serverworkspace/.metadata/.plugins/org.eclipse.core.runtime/
  15. 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/
  16.  
  17. $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.

  1. #!/bin/bash
  2.  
  3. # Create accounts on Orion server
  4. CURL=/usr/bin/curl
  5. SERVER=localhost
  6.  
  7. read -p "Username: " USER # Define the username
  8. read -p "Password: " PASS # Define the password
  9.  
  10. # Log in
  11. $CURL "http://$SERVER/login/form" \
  12.       -c curl_cookies.txt \ # Store cookies in this file
  13.       -d 'store=Orion'    \ # POST value: store type
  14.       -d 'login=admin'    \ # POST value: login
  15.       -d 'password=yourpass'
  16.  
  17. # Create one account
  18. # Loop here to create multiple accounts
  19. $CURL "http://$SERVER/users" \
  20.         -b curl_cookies.txt \ # Use this cookies file
  21.         -H "Orion-Version: 1" \ # Specify Orion version as an HTTP header
  22.         -d "login=$USER" \
  23.         -d "password=$PASS"
  24.  
  25. #add additional line after curl request.
  26. echo ""

Back to the top