Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Orion/Server admin guide
This page contains information on managing an Orion server.
Contents
- 1 Operating the server
- 2 Configuring the server
- 2.1 Server configuration file
- 2.2 Changing the port
- 2.3 Configuring paths where users can store files
- 2.4 Configuring project layout
- 2.5 Authentication type
- 2.6 Allowing users to create accounts
- 2.7 Creating an admin user
- 2.8 Creating and deleting users
- 2.9 Changing passwords
- 2.10 Enabling anonymous read access
- 2.11 Automatic git projects
- 2.12 Custom page footer
- 2.13 Configuring virtual host names for launching sites
- 3 Ongoing server management
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. This file is stored in the server workspace at the following location:
.metadata\.plugins\org.eclipse.core.runtime\.settings\org.eclipse.orion.server.configurator.prefs
You can manually create any of these parent directories if they don't exist yet. The file is a Java properties file with key/value pairs delimited by '=' character.
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.
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 org.eclipse.orion.server.core.allowedPathPrefixes system property needs to be edited. 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 property can be set in the eclipse.ini file:
-startup plugins/org.eclipse.equinox.launcher_1.2.0.v20110124-0830.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.100.v20101220 -consoleLog -console -data serverworkspace -vmargs -Dorg.eclipse.equinox.http.jetty.http.port=8080 -Dorg.eclipse.equinox.http.jetty.autostart=false -Dorg.eclipse.orion.server.core.allowedPathPrefixes=/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 "Auth-name" property in the server configuration file. For example, the following line will configure the server to use simple form-based authentication:
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 diallow user account creation, specify this property in the server configuration file:
everyoneCanCreateUsers=false
When this property is specified, account creation can only be performed on the user management page. This page is 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 launch the server with a special system property specifying the admin password:
eclipse -vmargs -Dorion.storage.admin.default.password=mypassword
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 system property. Once the admin account has been created, the system 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 to create a new user. To delete a user, click the 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 system property in eclipse.ini:
-Dorg.eclipse.orion.server.core.projectsWorldReadable=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 properties must be specified in the server configuration file:
orion.file.layout=userTree orion.project.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
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 must tell the Orion server what virtual host names will be used to host sites. This is done by setting the org.eclipse.orion.server.hosting.virtualHosts system property. In the --vmargs section of your eclipse\eclipse.ini file, you should add a line like this:
-Dorg.eclipse.orion.server.hosting.virtualHosts=*.planetorion.org
The value after the = sign is a list of domains (wildcards are allowed) and IP addresses, separated by commas. Each entry in the list must resolve to the Orion server, and will be used to assign unique host names to sites launched by users. 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. (On most platforms except Mac OS X, addresses from the 127.x.x.x range can be used for this purpose. You can also edit your platform's hosts file to create additional, readable aliases).
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
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