Markdown tweaks
Project: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/commit/ebacb960 Tree: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/tree/ebacb960 Diff: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/diff/ebacb960 Branch: refs/heads/master Commit: ebacb96065b85ce1279be5b3682d58bcb7b2f4bc Parents: 1fab628 Author: Stian Soiland-Reyes <st...@apache.org> Authored: Thu Dec 21 23:34:27 2017 +0000 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Thu Dec 21 23:34:27 2017 +0000 ---------------------------------------------------------------------- install.md | 97 ++++++++++++++++++++++++++------------------------------- 1 file changed, 44 insertions(+), 53 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/blob/ebacb960/install.md ---------------------------------------------------------------------- diff --git a/install.md b/install.md index c59fef8..35297ac 100644 --- a/install.md +++ b/install.md @@ -22,22 +22,22 @@ Apache Taverna Server Installation and Administration Guide * [Installation](#installation) * [Prerequisites](#prerequisites) * [Installation into Tomcat](#installation-into-tomcat) - * [Step 1. Configure Tomcat for JMX](#step-1-configure-tomcat-for-jmx) - * [Step 2. Configure Tomcat for General Management](#step-2-configure-tomcat-for-general-management) - * [Step 3. Prepare for T2Server WebApp Installation](#step-3-prepare-for-t2server-webapp-installation) - * [Step 4. Download the Webapp ARchive](#step-4-download-the-webapp-archive) - * [Step 5. Install the WebApp](#step-5-install-the-webapp) + * [Step 1. Configure Tomcat for JMX](#step-1-configure-tomcat-for-jmx) + * [Step 2. Configure Tomcat for General Management](#step-2-configure-tomcat-for-general-management) + * [Step 3. Prepare for T2Server WebApp Installation](#step-3-prepare-for-t2server-webapp-installation) + * [Step 4. Download the Webapp ARchive](#step-4-download-the-webapp-archive) + * [Step 5. Install the WebApp](#step-5-install-the-webapp) * [Firewall Requirements](#firewall-requirements) * [Details of Configuration](#details-of-configuration) * [Configuration Property List](#configuration-property-list) - * [Enabling Notification Options](#enabling-notification-options) + * [Enabling Notification Options](#enabling-notification-options) * [User Accounts](#user-accounts) * [Configuration of Impersonation](#configuration-of-impersonation) * [Security in Taverna Server](#security-in-taverna-server) - * [General](#general) - * [Architecture](#architecture) - * [Insecure Mode](#insecure-mode) - * [Part-Secure Mode](#part-secure-mode) + * [General](#general) + * [Architecture](#architecture) + * [Insecure Mode](#insecure-mode) + * [Part-Secure Mode](#part-secure-mode) * [Managing the Server](#managing-the-server) * [Component: Taverna/Server/Webapp](#component-tavernaserverwebapp) * [Component: Taverna/Server/RunFactory](#component-tavernaserverrunfactory) @@ -54,32 +54,26 @@ Installation ### Prerequisites -You will need **Linux**/**Unix** of some kind. +You will need **Linux**/**OS X** or other kind of **Unix**. Taverna Server has not been tested on Windows. -This software was developed against Debian Linux 5.0.9, but we anticipate that these instructions will apply equally to other Unixes. +You will need a **Java 8** (or later) installation (compile with 7) -You will need a **Java 7** (or later) installation. - -This software was developed and tested against the Oracle JRE 1.7.0\_21, and has also been tested against OpenJDK 7; use of the current version of either of these Java implementations is *recommended*. OpenJDK 6 cannot run this version of Taverna Server, nor can *gcj*. - -You will need a suitable **servlet container**. - -This software was developed using Tomcat 6.0.26 as the servlet container, but other versions of Tomcat are known to work (back to at least 6.0.20) and other containers may also function correctly as no Tomcat-specific APIs are used in the deployable code. We welcome feedback on which containers work, as well as on how to configure them (if they are not Tomcat versions). Using the current production release of Tomcat 6 is *recommended*. +You will need a suitable **servlet container**, for instance [Apache Tomcat](https://tomcat.apache.org/) ### Installation into Tomcat -Note that these instructions are Tomcat-specific. +Note that these instructions are Tomcat-specific using `context.xml` deployment that configures the path `/taverna-server`. You can also deploy by direct deployment of the WAR file, in which case you may want to rename it to `taverna-server.war` to avoid version-dependent deployment URIs. -The rest of this text assume your tomcat is running on http://localhost:8080/ - replace with equivalent `serverhost:port` for other installations. +The rest of this text assume your Tomcat server is running on http://localhost:8080/ - replace with equivalent `serverhost:port` for other installations. -#### Step 1. Configure Tomcat for JMX +#### Step 1. Configure Tomcat for JMX (optional) -If you're going to use JMX to administer the server (good for demos; jvisualvm is recommended if you've got the JMX support plugin, and jconsole is acceptable) then you need to edit Tomcat's `$TOMCATDIR/bin/startup.sh` script to include the setting: +If you're going to use [JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html) to administer the server (good for demos; `jvisualvm` is recommended if you've got the JMX support plugin; `jconsole` also works) then you need to edit Tomcat's `$TOMCATDIR/bin/startup.sh` script to include the setting: export CATALINA_OPTS=-Dcom.sun.management.jmxremote -This works around a minor bug in Spring which prevents correct registration of management beans in the default internal management service. You should also add additional options there to ensure that the JMX management layer is secure; see the Java JMX documentation for a discussion of how to do this. +This works around a minor bug in Spring which prevents correct registration of management beans in the default internal management service. You should also add additional options there to ensure that the JMX management layer is secure; see the [Java JMX documentation](https://docs.oracle.com/javase/tutorial/jmx/remote/index.html) for details. #### Step 2. Configure Tomcat for General Management @@ -91,7 +85,7 @@ Now start Tomcat (or restart it). #### Step 3. Prepare for T2Server WebApp Installation -Save the text below as context.xml on the machine where you are going to install the server. This is the minimum content of that file: +Save the text below as `context.xml` on the machine where you are going to install the server. This is the minimum content of that file: ```xml <Context path="/taverna-server"> @@ -116,7 +110,7 @@ Navigate to http://localhost:8080/manager/html and go to the Deploy box. Fill i Press the **Deploy** button; after a few seconds, Tomcat should respond with OK (at the top of the reloaded page) and you'll have the Taverna Server webapp installed at http://localhost:8080/taverna-server -Note that you **should** also review the section below on impersonation via sudo, which describes a reasonable minimal approach for securing the invocation of workflows as limited-authority users. Also be aware that *many features of this server software are disabled by default*, especially in relation to the pushing of notifications through other services (e.g., email, SMS). These features would be set through the use of context parameters, as described in the next section. +Note that you **should** also review the section below on impersonation via `sudo`, which describes a reasonable minimal approach for securing the invocation of workflows as limited-authority users. Also be aware that *many features of this server software are disabled by default*, especially in relation to the pushing of notifications through other services (e.g., email, SMS). These features would be set through the use of context parameters, as described in the next section. ### Firewall Requirements @@ -124,14 +118,12 @@ Taverna Server is a fairly network-intensive application, and the workflows it r For *incoming* ports, we recommend restricting them as much as is practical. In particular, we note that port 1099 is used by the service along with a substantial number of high-numbered ports: none of those need any access from outside the host system. The only ports that need to be opened are those that handle incoming user requests: in the default configuration of Tomcat, this would be port 8080 for HTTP traffic and 8443 for HTTPS traffic. (You will probably want to keep some other ports at least partially open for administration traffic, e.g., 22 for *ssh* access, but this is formally outside the scope of this document: Taverna Server itself does not need that.) -If you configure your firewall (or some sort of proxy) so that the host, port and web-application root that the user sees is not that which you are actually running the service on, you should set the *default.webapp* application parameter â typically via a deployment parameter â to a URL fragment giving the host, port and webapp root that you wish to use. (Taverna Server forces the protocol used separately.) +If you configure your firewall (or some sort of proxy) so that the host, port and web-application root that the user sees is not that which you are actually running the service on, you should set the `default.webapp` application parameter â typically via a deployment parameter â to a URL fragment giving the host, port and webapp root that you wish to use. (Taverna Server forces the protocol used separately.) ### Details of Configuration Deployment of web applications into Tomcat can be done through multiple mechanisms, notably through command line tools and through Tomcat's online administration interface. This document describes the latter mechanism. Note also that we currently only support the use of Taverna Server within a Unix environment (e.g., Linux, Mac OS X); there is no reason in principle why the code should not be adaptable to Microsoft Windows, but there is currently no impersonation module written to integrate Taverna Server with that operating platform. -This assumes that you installing into Tomcat 6 running on top of Java 7; this was tested with Tomcat 7.0.21 over the Oracle JRE 1.7.0\_21. Later patch versions from the same major version are recommended, if available. *This software has not been fully tested with Tomcat 7.* - The configuration of the Taverna Server installation is done by writing a context descriptor document, only some parts of which can be configured afterwards via the management interface. An *example* of that XML document is below: ```xml @@ -153,7 +145,7 @@ The actual deployment is done by giving the actual context location (i.e., the b ### Configuration Property List -This is a list of all the properties that are set by default in the Server (NB: the properties in red are actually unset or commented out by default, but they are all understood). They may be *all* overridden by the use of context configuration parameters as described above; for example, to override the default local user name, the default.localusername configuration parameter would be set. +This is a list of all the properties that are set (or empty) by default in the Server. They may be *all* overridden by the use of context configuration parameters as described above; for example, to override the default local user name, the default.localusername configuration parameter would be set. ***The majority of these properties should not be set,*** as they default to reasonable parameters. The exceptions are: @@ -203,8 +195,7 @@ default.operatinglimit: 10 secureForkPasswordFile: /usr/local/tomcat6.0/conf/sudopass.txt # URI to server's REST interface -taverna.preferredUserUri: - https://some.host:8443/taverna-server/rest/ +taverna.preferredUserUri: https://some.host:8443/taverna-server/rest/ # Delays used in the task executor, both in milliseconds purge.interval: 30000 @@ -219,10 +210,10 @@ usage.disableDB: no ### General configuration of messaging # cooldown in seconds -message.cooldown: 300 +message.cooldown: 300 message.termination.subject: Taverna workflow run finished -message.termination.body: Your job with ID={0} has finished with - exit code {1,number,integer}. +message.termination.body: Your job with ID={0} has finished with + exit code {1,number,integer}. ### Email-specific options email.from: taverna.server@localhost @@ -285,17 +276,17 @@ Atom notifications are always enabled; termination notifications are automatical ### User Accounts -Once you have deployed the server, you can use either JMX or the http://*«SERVER:PORT»*/taverna-server/admin interface to create and manage accounts. Only accounts with administrative permission can do such management. The initial set of users is loaded into the database from the WEB-INF/security/users.properties file in the deployment package; see the comments in that file for a more complete description of its contents; the file is only used if the user database is empty. +Once you have deployed the server, you can use either JMX or the http://localhost:8080/taverna-server/admin interface to create and manage accounts. Only accounts with administrative permission can do such management. The initial set of users is loaded into the database from the WEB-INF/security/users.properties file in the deployment package; see the comments in that file for a more complete description of its contents; the file is only used if the user database is empty. -By default, two enabled users are created. One is a normal user (taverna, with password taverna) and the other is an administrative user (admin, password admin). These defaults ***should be changed*** after installation, as they are not considered secure by default. More information about the mapping process is in the security summary document. +By default, two enabled users are created. One is a normal user (`taverna`, with password `taverna`) and the other is an administrative user (`admin`, password `admin`). These defaults ***should be changed*** after installation, as they are not considered secure by default. More information about the mapping process is in the security summary document. ### Configuration of Impersonation -If it is desired to separate each user of Taverna Server from the others, it is **necessary** to configure impersonation of users. That is, the user account that is running the servlet container (Tomcat, etc.) must have permission somehow to execute code as other users. (If this is not desired, the service should be configured to use the simpler non-impersonating worker factory â see the backEndFactory property above â or the fall-back user identity to use for impersonation should be set in the default.localusername to the same identity as the user account used for running the server.) +If it is desired to separate each user of Taverna Server from the others, it is **necessary** to configure impersonation of users. That is, the user account that is running the servlet container (Tomcat, etc.) must have permission somehow to execute code as other users. (If this is not desired, the service should be configured to use the simpler non-impersonating worker factory â see the `backEndFactory` property above â or the fall-back user identity to use for impersonation should be set in the `default.localusername` to the same identity as the user account used for running the server.) -This is done by either instructing the service what password is to be used with sudo (typically the password for the account that is invoking the sudo command) or by configuring sudo itself so that the service account is more highly authorized than a normal account. The first style of impersonation, which requires that the service account have a password at all, is enabled by creating a file (in a suitably secured directory) that contains the password as its only content, and telling Taverna Server about it during deployment by giving the full pathname of the file in the secureForkPasswordFile deployment parameter. +This is done by either instructing the service what password is to be used with `sudo` (typically the password for the account that is invoking the `sudo` command) or by configuring sudo itself so that the service account is more highly authorized than a normal account. The first style of impersonation, which requires that the service account have a password at all, is enabled by creating a file (in a suitably secured directory) that contains the password as its only content, and telling Taverna Server about it during deployment by giving the full pathname of the file in the secureForkPasswordFile deployment parameter. -The second style of impersonation is done by leaving that parameter unset and instead adding some extra configuration to the system's /etc/sudoers file, as seen below (typically set with the visudo command). Note that conventionally the three parts of the configuration are in separate sections of the file, and that care should be taken during configuration as mistakes can result in a system that is broken. In the example below, we assume that the servlet container is running as the Unix user tavserv and that local user accounts that may be targets for impersonation are all members of the taverna UNIX group. +The second style of impersonation is done by leaving that parameter unset and instead adding some extra configuration to the system's `/etc/sudoers` file, as seen below (typically set with the `visudo` command). Note that conventionally the three parts of the configuration are in separate sections of the file, and that care should be taken during configuration as mistakes can result in a system that is broken. In the example below, we assume that the servlet container is running as the Unix user `tavserv` and that local user accounts that may be targets for impersonation are all members of the `taverna` UNIX group. ```ini # Flags for the tavserv user (keep things quiet) @@ -321,7 +312,7 @@ In order to do this, it needs to be able to run code (specifically, a Java progr It is **recommended** that Taverna Server always be operated in secure mode, with all connections normally being made via HTTPS. Given that this requires that the container be configured with an SSL certificate, it should be noted that a single-host certificate is available from many certificate authorities for extremely limited cost (even free in some cases). Please consult your container's documentation on how to install the SSL certificate and configure the container for HTTPS operation. -If JMX is used for the management interface (depends on the container) it is **recommended** that it be configured to only accept authenticated connections over SSL. There is also an http://*«SERVER:PORT»*/taverna-server/admin REST interface to the server, which allows access to the same capabilities; it is only accessible to users which have the ROLE\_tavernasuperuser authority granted to them. Not all parts of the configuration can be managed in this way though; some properties are sufficiently fundamental that they can only be set through the configuration of the deployment descriptor. +If JMX is used for the management interface (depends on the container) it is **recommended** that it be configured to only accept authenticated connections over SSL. There is also an http://localhost:8080/taverna-server/admin REST interface to the server, which allows access to the same capabilities; it is only accessible to users which have the `ROLE_tavernasuperuser` authority granted to them. Not all parts of the configuration can be managed in this way though; some properties are sufficiently fundamental that they can only be set through the configuration of the deployment descriptor. #### Architecture @@ -331,26 +322,26 @@ Authorisation of users is done through the use of Spring Security to assign them - `ROLE_tavernauser` â allows the user to access the main operational parts of the server. -- `ROLE_tavernasuperuser` â allows the user to read and write all non-security characteristics of all workflows, and also grants access to the http://*«SERVER:PORT»*/taverna-server/admin pages. +- `ROLE_tavernasuperuser` â allows the user to read and write all non-security characteristics of all workflows, and also grants access to the http://localhost:8080/taverna-server/admin pages. - `LOCALUSER_*` (where the `*` is replaced with a local user name) â specifies what local user name the user should be executing workflows as; the prefix (`LOCALUSER_`) is simply stripped and the remainder is used as a user name. If absent, the default user name (taverna in the default configuration) will be used; two users mapped to the same user name will be able to see each others workflows if they can work out where the job working directories are located, but will not be able to see them inside Taverna Server itself (unless one user grants the other authority to do so, of course). -The default source of authorities is the file WEB-INF/security/users.properties (relative to the directory which is the expanded webapp) that is used to populate the database if that is empty. +The default source of authorities is the file `WEB-INF/security/users.properties` (relative to the directory which is the expanded webapp) that is used to populate the database if that is empty. #### Insecure Mode -The server can be switched into insecure mode by editing its WEB-INF/web.xml file so that it pulls its Spring configuration from insecure.xml instead of from secure.xml (the default) via the contextConfigLocation parameter. When editing WEB-INF/web.xml, the webapp must be stopped and restarted for any changes to be noticed. This alternate configuration disabled URI rewriting, restricts the set of users to a single one (taverna with a password taverna) and arranges for execution of workflow runs to be done in the same local userid as is running the host servlet container (Tomcat, etc.) +The server can be switched into insecure mode by editing its `WEB-INF/web.xml` file so that it pulls its Spring configuration from `insecure.xml` instead of from `secure.xml` (the default) via the `contextConfigLocation` parameter. When editing WEB-INF/web.xml, the webapp must be stopped and restarted for any changes to be noticed. This alternate configuration disabled URI rewriting, restricts the set of users to a single one (`taverna` with a password `taverna`) and arranges for execution of workflow runs to be done in the same local userid as is running the host servlet container (Tomcat, etc.) If you are using this, it is *strongly* ***recommended*** that you place the server behind a strong firewall and portal, and only permit vetted workflows to be used. #### Part-Secure Mode -There is a partially-secured configuration as well. This enables the forced use of HTTPS, but disables the use of user separation by the back-end engine, giving an intermediate level of security suitable for the case where the network is *not* trusted but the permitted users *are* trusted. You may enable this mode by using partsecure.xml as the value of the contextConfigLocation parameter in WEB-INF/web.xml after installation (the webapp must be stopped while you make this change). Note that because HTTPS is being used, you will still need to configure the servlet container with an SSL keypair for this to work. +There is a partially-secured configuration as well. This enables the forced use of HTTPS, but disables the use of user separation by the back-end engine, giving an intermediate level of security suitable for the case where the network is *not* trusted but the permitted users *are* trusted. You may enable this mode by using `partsecure.xml` as the value of the `contextConfigLocation` parameter in `WEB-INF/web.xml` after installation (the webapp must be stopped while you make this change). Note that because HTTPS is being used, you will still need to configure the servlet container with an SSL keypair for this to work. Managing the Server ------------------- -The server is designed to support JMX for management. This allows the use of tools such as jconsole or jvisualvm (with appropriate plugin) to connect to the server so that they can view, chart, and manipulate properties of the server. The exact list of properties is liable to change, but is as follows in this release: +The server is designed to support [JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html) for management. This allows the use of tools such as jconsole or jvisualvm (with appropriate plugin) to connect to the server so that they can view, chart, and manipulate properties of the server. The exact list of properties is liable to change, but is as follows in this release: ### Component: Taverna/Server/Webapp @@ -399,13 +390,13 @@ This is an interface for adding, deleting and otherwise managing user accounts o | **Operation** | **Description** | |-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **addUser(*nm,pw,cpl*)** | Adds the user called *nm* to the database, with password *pw*. If *cpl* is true, set the local user account to be the same as the user name, otherwise use a default set at system configuration time. The user will be a non-admin and disabled by default. | -| **deleteUser(*nm*)** | Remove the user called *nm* from the database. | -| **getUserInfo(*nm*)** | Get a description of the user called *nm* from the database. | -| **setUserAdmin(*nm,ad*)** | Set whether the user called *nm* is an admin or not (according to the boolean, *ad*). | -| **setUserEnabled(*nm,en*)** | Set whether the user called *nm* is an admin or not (according to the boolean, *en*). | -| **setUserLocalUser(*nm,lu*)** | Set what the user called *nm* will be mapped to as a local user to *lu* (which must be the name of an account understood by the local system). | -| **setUserPassword(*nm,pw*)** | Set the password for the user *nm* to be *pw*. This implementation stores the value directly in the database. | +| **addUser(`nm`,`pw`,`cpl`)** | Adds the user called `nm` to the database, with password `ow`. If `cpl` is true, set the local user account to be the same as the user name, otherwise use a default set at system configuration time. The user will be a non-admin and disabled by default. | +| **deleteUser(`nm`)** | Remove the user called `nm` from the database. | +| **getUserInfo(`nm`)** | Get a description of the user called `nm` from the database. | +| **setUserAdmin(`nm`,`ad`)** | Set whether the user called `nm` is an admin or not (according to the boolean, `ad`). | +| **setUserEnabled(`nm`,`en`)** | Set whether the user called `nm` is an admin or not (according to the boolean, `en`). | +| **setUserLocalUser(`nm`,`lu`)** | Set what the user called `nm` will be mapped to as a local user to `lu` (which must be the name of an account understood by the local system). | +| **setUserPassword(`nm`,`pw`)** | Set the password for the user `nm` to be `ow`. This implementation stores the value directly in the database. | The server also supports a RESTful administration interface on its http://localhost:8080/taverna-server/admin resource (a sibling to the main RESTful http://localhost:8080/taverna-server/rest resource and the Atom feed on http://localhost:8080/taverna-server/feed). This interface is only available to users who authenticate with admin permissions. Currently, there is no rendering of the interface in a form that is suitable for use from a normal web browser; this is expected to change in future versions.
