Configuring the server | ||
---|---|---|
![]() |
![]() |
|
Server administration guide | Administering users |
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 - 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 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.
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.
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
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..
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
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.
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
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
On Windows two backslashes must be used to separate path entries:
orion.file.allowedPaths=C:\\Users\\orion
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
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+OpenID
Valid values for this property are:
Basic
: Basic HTTP authentication (not secure unless running on https)FORM+OpenID
: User can select form-based authentication or OpenID authenticationOrion supports login using Mozilla Persona. To log in with Persona, a user must sign in with Persona using the same email address that is associated to their Orion account.
Mozilla Persona credentials supplied by a user are verified against an "audience" parameter, which identifies the server (scheme + domain + port) they're trying to log in to. The following property sets the audience parameter that your server expects. The value of this property should exactly match the client-facing URL of your website. For example, here is what an entry for orionhub.org would look like:
orion.auth.host=http://orionhub.org:80
If this property is not set, Orion will only allow Persona logins from a local loopback device (localhost, 127.0.0.1, etc.). All other attempts attempts to log in with Persona will fail with a message like this:
When logging in with Mozilla Persona credentials, the user's information is verified using a third-party web service. The following property specifies the URL of the service to be used:
orion.auth.persona.verifier=https://verifier.login.persona.org/verify
If this property is not set,
https://verifier.login.persona.org/verify
is used by default.
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
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
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
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
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
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:
*.example.org
, or
https://*.example.org
.
foo.example.org
.
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).
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.
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 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
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
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.
Orion 4.0 introduced a new <dfn>simple</dfn> format for backend storage of metadata (users, workspaces, and projects) on the server, intended to provide better scalability and easier administration. To use the new format, set the orion.core.metastore
property to simple
. In Orion 4.0, you should also set the orion.file.layout
property, so the following should be in the orion.conf
:
orion.core.metastore=simple orion.file.layout=userTree
To use the old metadata format from Orion 3.0 and earlier, specify legacy
:
orion.core.metastore=legacy
If the orion.core.metastore
property is not provided, the legacy
format is used by default.
orion.core.metastore=simple
against an existing pre-4.0 server workspace will migrate the workspace to the simple format. The migration is irreversible, so you should create a backup copy of the server workspace before attempting this. Consult the
Metadata migration page for more details.
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.
![]() |
![]() |
![]() |
Server administration guide | Administering users |