Repository: incubator-taverna-server Updated Branches: refs/heads/master 2eeec9a9c -> a58372758
copied back from taverna-site https://taverna.incubator.apache.org/documentation/server/ 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/a5837275 Tree: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/tree/a5837275 Diff: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/diff/a5837275 Branch: refs/heads/master Commit: a583727586dd558c91b9570c5b9ea069c9978224 Parents: 2eeec9a Author: Stian Soiland-Reyes <[email protected]> Authored: Fri Jan 19 01:03:18 2018 +0000 Committer: Stian Soiland-Reyes <[email protected]> Committed: Fri Jan 19 01:05:11 2018 +0000 ---------------------------------------------------------------------- README.md | 269 ++++--------------- install.md | 257 +++++++++--------- introduction.md | 275 +++++++++++++++++++ usage.md | 743 +++++++++++++++++++++++---------------------------- 4 files changed, 789 insertions(+), 755 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/blob/a5837275/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 64a0752..6976173 100644 --- a/README.md +++ b/README.md @@ -110,230 +110,65 @@ that enforces Apache headers in every source file - to disable it, try: mvn clean install -Drat.skip=true +More information: -## A Beginner's Installation Guide to Taverna Server + * [Introduction](introduction.md) + * [Installing](install.md) + * [Using](usage.md) -When installing Taverna Server, you *need* to decide whether to -install in secure or insecure mode. In secure mode, the server -enforces logins, ensures that they are done over HTTPS, and applies -strong restrictions to what users can see of other users' -workflows. In insecure mode, no restrictions are enforced which -simplifies configuration but greatly reduces the overall system -security. *Do not mix up installations between the two types.* -You will need: - -* **Unix** (e.g., Linux, OSX). Running Linux inside a virtual machine - or in Docker works. Running directly on Windows is not supported. - -* **Java 8** (or later). - -* **Apache Tomcat** (use most recent version). - -If you are installing in secured mode (default) you will also need: - -* **SSL** (i.e., HTTPS) **host certificate**. This should not be - self-signed and should have the hostname in the Common Name (CN) - field. (Self-signed certificates or ones without the hostname in are - exceptionally awkward for clients to work with, and proper - single-host certificates are in reality very cheap. Save yourself a - lot of work here!) - -* For the simplest operation, you should create a user `taverna` that is - a member of the group called `taverna`. This user will be used for - executing workflows, and does not need to allow anyone to log in as - it. - -Stick to the Factory Defaults ------------------------------ - -Taverna Server has a long list of things that may be configured, -but it comes with âfactoryâ settings that are correct in the majority -of cases. Leave them alone for your first installation. - -Setting up Apache Tomcat ------------------------- - -Note that the instructions below do not describe setting up Tomcat -users. These are not necessary for Taverna Server, as that needs -finer-grained permission control than is normal for a webapp. - - -### Installing on Debian Linux, Ubuntu - -On Debian Linux (and derivatives), you install Tomcat with: - - sudo apt-get install tomcat8 tomcat8-admin tomcat8-common tomcat8-user - -You then start Tomcat with: - - sudo /etc/init.d/tomcat8 start - -And stop it with: - - sudo /etc/init.d/tomcat8 stop - -It's configuration file (called `conf/server.xml` in the instructions below) will be in: - - /etc/tomcat8/server.xml - -It's webapp directory (`webapps` below) will be in: - - /var/lib/tomcat8/webapps/ - -### Installing on RedHat Linux, Fedora, CentOS, Scientific Linux - -On RedHat Linux (and derivatives), you install Tomcat with: - - yum install tomcat8-webapps - -You then start Tomcat with: - - sudo service tomcat8 start - -And stop it with: - - sudo service tomcat8 stop - -It's configuration file (called `conf/server.xml` in the instructions below) will be in: - - /etc/tomcat8/server.xml - -It's webapp directory (`webapps` below) will be in: - - /var/lib/tomcat8 - -### Installing on MacOS X, and using a baseline Apache distribution - -On OSX (or if otherwise installing from a standard Apache -distribution), you install Tomcat by downloading from the distribution -page at: - -* http://tomcat.apache.org/ - -Both ZIP and `.tar.gz` download versions include a file `RUNNING.txt` -that describes how to perform the installation, start the server, and -stop it again. - -The normal location of the configuration file (`conf/server.xml` in -the instructions below) is, for Tomcat 6.0.35: - - /usr/local/tomcat6.0/apache-tomcat-6.0.35/conf/server.xml - -And its `webapps` directory is at: - - /usr/local/tomcat6.0/apache-tomcat-6.0.35/webapps - -Installing an Unsecured Taverna Server --------------------------------------- - -This is not the default configuration of Taverna Server because it is -_insecure_; there is no attempt to verify the identity of users or to -keep them from interfering with each other's workflows. _We recommend -that you use the secured version if possible._ - -The insecure version is installed by: - -### First, place the WAR into Tomcat's webapps directory - -You may use a filename that relates to what URL you want Taverna Server to -appear at within Tomcat (e.g., if you want it to be at `/taverna`, use the -filename `webapps/taverna.war`). - -### Next, start Tomcat (if stopped), and shut it down again once it has unpacked the WAR. - -At this point, Taverna Server is installed but not usable. - -### Then configure for unsecure operation. - -Go to the unpacked WAR, find its `WEB-INF/web.xml` (with the above -installation path, it would be -`webapps/tavernaserver/WEB-INF/web.xml`), and change the lines: - - <param-value>WEB-INF/secure.xml</param-value> - <!-- <param-value>WEB-INF/insecure.xml</param-value> --> - -to read: - - <!-- <param-value>WEB-INF/secure.xml</param-value> --> - <param-value>WEB-INF/insecure.xml</param-value> - -This changes which part of the rest of the server configuration is -used. It does so by altering what part of that XML file are commented -out. One of those two `<param-value>` lines **must** be -uncommented. The overall XML file **must** be valid. - -### Finally, start Tomcat. - -> **NB:** When accessing an unsecured Taverna Server, for most - operations (such as submitting a run) you will need to pass the - credentials for the default user. The default user has username - `taverna` and password `taverna`. - -Installing a Secured Taverna Server ------------------------------------ -Taverna Server 2.5 is installed in secure mode by doing this: - -### First you need to enable SSL on Tomcat. - -With Tomcat not running, make sure that its `conf/server.xml` file -contains a `<Connector>` definition for SSL HTTP/1.1. The file should -contain comments on how to do this. Here's an example: - - <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" - maxThreads="150" scheme="https" secure="true" - clientAuth="false" sslProtocol="TLS" keystorePass="tomcat" - keystoreFile="conf/tavserv.p12" keystoreType="PKCS12" /> - -This configuration enables secure access on port 8443 (HTTPS-alt; -strongly recommended) with the server using the key-pair that has been -placed in a standard PKCS #12 format file in the file `tavserv.p12` in -the same directory as the configuration file; the key-pair file will -be unlocked with the (rather obvious) password â`tomcat`â. - -Note that if the configuration file is located below `/etc`, it is -recommended that you specify the full path to the PKCS #12 file. You -should also ensure that the file can only be read by the Unix user -that will be running Tomcat. - -### Next, you need to grant permission to the Tomcat server to run code as other users. - -In particular, it needs to be able to run the Java executable it is -using as other people via `sudo`. You _should_ take care to lock this -down heavily. You do this by using the program visudo to add these -parts to the sudo configuration. Note that each goes in a separate -part of the overall file, and that we assume below that Tomcat is -running as the user `tavserv`; you will probably need to change (e.g., -to `tomcat` or `nobody`) as appropriate. - -This defines some flags for the main server user: - - Defaults:tavserv !lecture, timestamp_timeout=0, passwd_tries=1 - -This defines a rule for who the server can switch to. Let's say that -they have to be a member of the Unix user group `taverna`; if a user -isn't in that group, they cannot use Taverna Server. (Note that `root` -should not be part of the group!) - - Runas_Alias TAV = %taverna - -This creates the actual permission, saying that the `tavserv` user may -run anything as any user in the alias above (i.e., in the `taverna` -group). The `NOPASSWD` is important because it allows Taverna Server -to do the delegation even when running as a user that can't log in. - - tavserv ALL=(TAV) NOPASSWD: ALL +# Export restrictions -### Now, place the WAR into Tomcat's `webapps` directory. +This distribution includes cryptographic software. +The country in which you currently reside may have restrictions +on the import, possession, use, and/or re-export to another country, +of encryption software. BEFORE using any encryption software, +please check your country's laws, regulations and policies +concerning the import, possession, or use, and re-export of +encryption software, to see if this is permitted. +See <http://www.wassenaar.org/> for more information. -You may use a filename that relates to what URL you want Taverna Server to -appear at within Tomcat (e.g., if you want it to be deployed at -`/taverna`, rename the WAR to a filename like `webapps/taverna.war`). +The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), +has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, +which includes information security software using or performing +cryptographic functions with asymmetric algorithms. +The form and manner of this Apache Software Foundation distribution makes +it eligible for export under the License Exception +ENC Technology Software Unrestricted (TSU) exception +(see the BIS Export Administration Regulations, Section 740.13) +for both object code and source code. -### Finally, start Tomcat. +The following provides more details on the included cryptographic software: -Taverna Server should then become available at -the equivalent of http://localhost:8080/taverna-server/ +* Taverna Server's `CertificateChainFetcher` uses + [Java Secure Socket Extension](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html) + (JSS) to pre-fetch certificates of SSL-secured web services accessed by Taverna workflows. +* Taverna Server's support for propagating username/password credentials in + `SecurityContextFactory` relies on + [BouncyCastle](https://www.bouncycastle.org/) bcprov encryption library and + [Java Cryptography Extension](http://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html) + (JCE) to generate a keystore for Taverna Command-line tool. + The [JCE Unlimited Strength Jurisdiction Policy](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html) + may need to be installed separately. +* Taverna Server may interact with the credential manager support in + [Apache Taverna Command-line Tool](https://taverna.incubator.apache.org/download/commandline/) + to provide a keystore of client credentials and trusted certificates for SSL-secured web services. +* After building, the + `taverna-server-webapp/target/taverna-server.war` will include + dependencies that are covered + by export restrictions, including: + [BouncyCastle](https://www.bouncycastle.org/) bcprov encryption library, + [Apache HttpComponents](https://hc.apache.org/) Core and Client, + [Apache Derby](http://db.apache.org/derby/), + [Jetty](http://www.eclipse.org/jetty/), + [Apache WSS4J](https://ws.apache.org/wss4j/), + [Apache XML Security for Java](https://santuario.apache.org/javaindex.html), + [Open SAML Java](https://shibboleth.net/products/opensaml-java.html), + [Apache Taverna Language](https://taverna.incubator.apache.org/download/language/), + [Apache Taverna OSGi](https://taverna.incubator.apache.org/download/osgi/), + [Apache Taverna Engine](https://taverna.incubator.apache.org/download/engine/), + [Apache Taverna Common Activities](https://taverna.incubator.apache.org/download/common-activities/), + and [Apache Taverna Command-line Tool](https://taverna.incubator.apache.org/download/commandline/). # Export restrictions http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/blob/a5837275/install.md ---------------------------------------------------------------------- diff --git a/install.md b/install.md index 35297ac..71f29b3 100644 --- a/install.md +++ b/install.md @@ -87,10 +87,8 @@ Now start Tomcat (or restart it). 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"> -</Context> -``` + <Context path="/taverna-server"> + </Context> Additional configuration properties can be set in the context.xml file; see the detailed deployment description section of this document for more information. @@ -126,18 +124,16 @@ Deployment of web applications into Tomcat can be done through multiple mechanis 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 -<Context path="/taverna-server"> - <!-- Sample logging configuration. --> - <Valve className="org.apache.catalina.valves.AccessLogValve" /> - - <Parameter name="default.localusername" - value="localtavernauser" /> - - <!-- For email-dispatched notifications. --> - <Parameter name="email.host" value="localhost" /> -</Context> -``` + <Context path="/taverna-server"> + <!-- Sample logging configuration. --> + <Valve className="org.apache.catalina.valves.AccessLogValve" /> + + <Parameter name="default.localusername" + value="localtavernauser" /> + + <!-- For email-dispatched notifications. --> + <Parameter name="email.host" value="localhost" /> + </Context> The context descriptor is typically in a file called context.xml and there is a sample context descriptor with this distribution, in the context.sample.xml file. There are a substantial number of properties that may be tuned during installation (see below). @@ -151,110 +147,111 @@ This is a list of all the properties that are set (or empty) by default in the S - Those used to control how many runs exist and are operating at once. The default.runlimit and default.operatinglimit have reasonable initial values, but must be tuned according to the actual expected workload. They can be set at runtime via the administration web interface and via JMX. -- Those used to enable optional notification mechanisms; those are all disabled by default unless the required extra properties are set (see below for instructions). - -```ini -# Script in Taverna installation to run to actually execute workflows -executeWorkflowScript: /usr/taverna/executeworkflow.sh - -# Override the hostname, port and webapp; leave at 'NONE' if no -# override desired. If set, set it to something like: -# foo.example.com:8000/tav-serv -default.webapp: NONE - -# User name to use by default for impersonation if nothing else -# specified -default.localusername: taverna - -# The HTTP authorization realm; should be different from all other -# webapps on the deployment server -http.realmName: tavernaserver - -# Force the RMI registry to only listen to connections from localhost -# Should be true unless you have a good reason to open it up. -rmi.localhostOnly: true - -# How to pick a user name out of a global identity -localusernameregexp: ^TAVERNAUSER=(.*)$ -# Whether to log incoming workflows; noisy if enabled -default.logworkflows: false -# Whether to log outgoing exceptions; noisy if enabled -default.logexceptions: false -# Whether to allow workflows to be submitted; adjustable via admin -# interfaces -default.permitsubmit: true -# How long a workflow run should live by default, in seconds -default.lifetime: 1440 -# Maximum number of simultaneous workflow runs, in any state -default.runlimit: 100 -# Maximum number of simultaneous *operating* workflow runs (i.e., -# that are actually running) -default.operatinglimit: 10 - -# Location of impersonation credentials -secureForkPasswordFile: /usr/local/tomcat6.0/conf/sudopass.txt - -# URI to server's REST interface -taverna.preferredUserUri: https://some.host:8443/taverna-server/rest/ - -# Delays used in the task executor, both in milliseconds -purge.interval: 30000 -finish.interval: 10000 - -# Thread pool sizing -pool.size: 2 - -### Usage Record handling -usage.logFile: none -usage.disableDB: no - -### General configuration of messaging -# cooldown in seconds -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}. - -### Email-specific options -email.from: taverna.server@localhost -email.type: text/plain -email.host: localhost - -### Jabber-specific options -xmpp.server: xmpp://some.host:5222 -xmpp.resource: TavernaServer -xmpp.user: taverna -xmpp.password: ******* - -### Atom/RSS feed; lifespan in days, cleaninterval in milliseconds -atom.language: en -atom.lifespan: 7 -atom.cleaninterval: 3600000 - -### SMS-specific options -sms.service: - https://www.intellisoftware.co.uk/smsgateway/sendmsg.aspx -sms.userfield: username -sms.passfield: password -sms.destfield: to -sms.msgfield: text -sms.user: taverna -sms.pass: ******* - -### Twitter-specific options -twitter.oauth.accessToken: ******* -twitter.oauth.accessTokenSecret: ******* - -### Special options -# Do detailed logging of security. The information logged is enough -# to allow an administrator to recover arbitrary user credentials, -# so this should be false under normal circumstances. -log.security.details: false - -# Enables a special project-specific security setting. -# Leave at false unless you have been specifically told otherwise. -helio.cis.enableTokenPassing: false -``` +- Those used to enable optional notification mechanisms; those are all disabled by default unless the required extra properties are set (see below). + +Complete property configuration: + + # Script for Taverna command line tool to actually execute workflows + executeWorkflowScript: /usr/taverna/executeworkflow.sh + + # Override the hostname, port and webapp; leave at 'NONE' if no + # override desired. If set, set it to something like: + # foo.example.com:8000/tav-serv + default.webapp: NONE + + # User name to use by default for impersonation if nothing else + # specified + default.localusername: taverna + + # The HTTP authorization realm; should be different from all other + # webapps on the deployment server + http.realmName: tavernaserver + + # Force the RMI registry to only listen to connections from localhost + # Should be true unless you have a good reason to open it up. + rmi.localhostOnly: true + + # How to pick a user name out of a global identity + localusernameregexp: ^TAVERNAUSER=(.*)$ + # Whether to log incoming workflows; noisy if enabled + default.logworkflows: false + # Whether to log outgoing exceptions; noisy if enabled + default.logexceptions: false + # Whether to allow workflows to be submitted; adjustable via admin + # interfaces + default.permitsubmit: true + # How long a workflow run should live by default, in seconds + default.lifetime: 1440 + # Maximum number of simultaneous workflow runs, in any state + default.runlimit: 100 + # Maximum number of simultaneous *operating* workflow runs (i.e., + # that are actually running) + default.operatinglimit: 10 + + # Location of impersonation credentials + secureForkPasswordFile: /usr/local/tomcat6.0/conf/sudopass.txt + + # URI to server's REST interface + taverna.preferredUserUri: https://some.host:8443/taverna-server/rest/ + + # Delays used in the task executor, both in milliseconds + purge.interval: 30000 + finish.interval: 10000 + + # Thread pool sizing + pool.size: 2 + + ### Usage Record handling + usage.logFile: none + usage.disableDB: no + + ### General configuration of messaging + # cooldown in seconds + 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}. + + ### Email-specific options + email.from: taverna.server@localhost + email.type: text/plain + email.host: localhost + + ### Jabber-specific options + xmpp.server: xmpp://some.host:5222 + xmpp.resource: TavernaServer + xmpp.user: taverna + xmpp.password: ******* + + ### Atom/RSS feed; lifespan in days, cleaninterval in milliseconds + atom.language: en + atom.lifespan: 7 + atom.cleaninterval: 3600000 + + ### SMS-specific options + sms.service: + https://www.intellisoftware.co.uk/smsgateway/sendmsg.aspx + sms.userfield: username + sms.passfield: password + sms.destfield: to + sms.msgfield: text + sms.user: taverna + sms.pass: ******* + + ### Twitter-specific options + twitter.oauth.accessToken: ******* + twitter.oauth.accessTokenSecret: ******* + + ### Special options + # Do detailed logging of security. The information logged is enough + # to allow an administrator to recover arbitrary user credentials, + # so this should be false under normal circumstances. + log.security.details: false + + # Enables a special project-specific security setting. + # Leave at false unless you have been specifically told otherwise. + helio.cis.enableTokenPassing: false + #### Enabling Notification Options @@ -288,17 +285,15 @@ This is done by either instructing the service what password is to be used with 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) -Defaults:tavserv !lecture, timestamp_timeout=0, passwd_tries=1 - -# Who can we impersonate? Manage via Unix group called 'taverna' -Runas_Alias TAV = %taverna - -# The actual permission to impersonate, with permission to run -# anything -tavserv ALL=(TAV) NOPASSWD: ALL -``` + # Flags for the tavserv user (keep things quiet) + Defaults:tavserv !lecture, timestamp_timeout=0, passwd_tries=1 + + # Who can we impersonate? Manage via Unix group called 'taverna' + Runas_Alias TAV = %taverna + + # The actual permission to impersonate, with permission to run + # anything + tavserv ALL=(TAV) NOPASSWD: ALL Care should be taken as without a password specified and without permission to execute as another user, an attempt to create a workflow run will hang instead of failing. http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/blob/a5837275/introduction.md ---------------------------------------------------------------------- diff --git a/introduction.md b/introduction.md new file mode 100644 index 0000000..6cc026c --- /dev/null +++ b/introduction.md @@ -0,0 +1,275 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +# Apache Taverna Server (incubating) + +Taverna Server is a REST/WSDL web service for executing +[Apache Taverna](http://taverna.incubator.apache.org/) (incubating) +workflows. + +In-depth documentation is available for: + +* [Installation guide](install) +* [API User guide](usage) + + +# Prerequisites + +* Java 1.8 +* [Apache Maven](https://maven.apache.org/download.html) 3.3.9 or newer +* a Java Servlet container, e.g. [Apache Tomcat](https://tomcat.apache.org/) + + +# Building + +After [downloading Taverna Server](/download/server/) and unpacking, +then to build, use: + + mvn clean install + +This will build each module and run their tests. + +You should then find `taverna-server.war` in the folder +`taverna-server-webapp/target/` + +Below we'll show how to install and configure this _WAR file_ +with Apache Tomcat. + + +## A Beginner's Installation Guide to Taverna Server + +When installing Taverna Server, you *need* to decide whether to +install in secure or insecure mode. In secure mode, the server +enforces logins, ensures that they are done over HTTPS, and applies +strong restrictions to what users can see of other users' +workflows. In insecure mode, no restrictions are enforced which +simplifies configuration but greatly reduces the overall system +security. *Do not mix up installations between the two types.* + +You will need: + +* **Unix** (e.g., Linux, OSX). Running Linux inside a virtual machine + or in Docker works. Running directly on Windows is not supported. + +* **Java 8** (or later). + +* **Apache Tomcat** (use most recent version). + +If you are installing in secured mode (default) you will also need: + +* **SSL** (i.e., HTTPS) **host certificate**. This should not be + self-signed and should have the hostname in the Common Name (CN) + field. (Self-signed certificates or ones without the hostname in are + exceptionally awkward for clients to work with, and proper + single-host certificates are in reality very cheap. Save yourself a + lot of work here!) + +* For the simplest operation, you should create a user `taverna` that is + a member of the group called `taverna`. This user will be used for + executing workflows, and does not need to allow anyone to log in as + it. + +Stick to the Factory Defaults +----------------------------- + +Taverna Server has a long list of things that may be configured, +but it comes with âfactoryâ settings that are correct in the majority +of cases. Leave them alone for your first installation. + +Setting up Apache Tomcat +------------------------ + +Note that the instructions below do not describe setting up Tomcat +users. These are not necessary for Taverna Server, as that needs +finer-grained permission control than is normal for a webapp. + + +### Installing on Debian Linux, Ubuntu + +On Debian Linux (and derivatives), you install Tomcat with: + + sudo apt-get install tomcat8 tomcat8-admin tomcat8-common tomcat8-user + +You then start Tomcat with: + + sudo /etc/init.d/tomcat8 start + +And stop it with: + + sudo /etc/init.d/tomcat8 stop + +It's configuration file (called `conf/server.xml` in the instructions below) will be in: + + /etc/tomcat8/server.xml + +It's webapp directory (`webapps` below) will be in: + + /var/lib/tomcat8/webapps/ + +### Installing on RedHat Linux, Fedora, CentOS, Scientific Linux + +On RedHat Linux (and derivatives), you install Tomcat with: + + yum install tomcat8-webapps + +You then start Tomcat with: + + sudo service tomcat8 start + +And stop it with: + + sudo service tomcat8 stop + +It's configuration file (called `conf/server.xml` in the instructions below) will be in: + + /etc/tomcat8/server.xml + +It's webapp directory (`webapps` below) will be in: + + /var/lib/tomcat8 + +### Installing on MacOS X, and using a baseline Apache distribution + +On OSX (or if otherwise installing from a standard Apache +distribution), you install Tomcat by downloading from the distribution +page at: + +* http://tomcat.apache.org/ + +Both ZIP and `.tar.gz` download versions include a file `RUNNING.txt` +that describes how to perform the installation, start the server, and +stop it again. + +The normal location of the configuration file (`conf/server.xml` in +the instructions below) is, for Tomcat 6.0.35: + + /usr/local/tomcat6.0/apache-tomcat-6.0.35/conf/server.xml + +And its `webapps` directory is at: + + /usr/local/tomcat6.0/apache-tomcat-6.0.35/webapps + +Installing an Unsecured Taverna Server +-------------------------------------- + +This is not the default configuration of Taverna Server because it is +_insecure_; there is no attempt to verify the identity of users or to +keep them from interfering with each other's workflows. _We recommend +that you use the secured version if possible._ + +The insecure version is installed by: + +### First, place the WAR into Tomcat's webapps directory + +You may use a filename that relates to what URL you want Taverna Server to +appear at within Tomcat (e.g., if you want it to be at `/taverna`, use the +filename `webapps/taverna.war`). + +### Next, start Tomcat (if stopped), and shut it down again once it has unpacked the WAR. + +At this point, Taverna Server is installed but not usable. + +### Then configure for unsecure operation. + +Go to the unpacked WAR, find its `WEB-INF/web.xml` (with the above +installation path, it would be +`webapps/tavernaserver/WEB-INF/web.xml`), and change the lines: + + <param-value>WEB-INF/secure.xml</param-value> + <!-- <param-value>WEB-INF/insecure.xml</param-value> --> + +to read: + + <!-- <param-value>WEB-INF/secure.xml</param-value> --> + <param-value>WEB-INF/insecure.xml</param-value> + +This changes which part of the rest of the server configuration is +used. It does so by altering what part of that XML file are commented +out. One of those two `<param-value>` lines **must** be +uncommented. The overall XML file **must** be valid. + +### Finally, start Tomcat. + +> **NB:** When accessing an unsecured Taverna Server, for most + operations (such as submitting a run) you will need to pass the + credentials for the default user. The default user has username + `taverna` and password `taverna`. + +Installing a Secured Taverna Server +----------------------------------- +Taverna Server 2.5 is installed in secure mode by doing this: + +### First you need to enable SSL on Tomcat. + +With Tomcat not running, make sure that its `conf/server.xml` file +contains a `<Connector>` definition for SSL HTTP/1.1. The file should +contain comments on how to do this. Here's an example: + + <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" + maxThreads="150" scheme="https" secure="true" + clientAuth="false" sslProtocol="TLS" keystorePass="tomcat" + keystoreFile="conf/tavserv.p12" keystoreType="PKCS12" /> + +This configuration enables secure access on port 8443 (HTTPS-alt; +strongly recommended) with the server using the key-pair that has been +placed in a standard PKCS #12 format file in the file `tavserv.p12` in +the same directory as the configuration file; the key-pair file will +be unlocked with the (rather obvious) password â`tomcat`â. + +Note that if the configuration file is located below `/etc`, it is +recommended that you specify the full path to the PKCS #12 file. You +should also ensure that the file can only be read by the Unix user +that will be running Tomcat. + +### Next, you need to grant permission to the Tomcat server to run code as other users. + +In particular, it needs to be able to run the Java executable it is +using as other people via `sudo`. You _should_ take care to lock this +down heavily. You do this by using the program visudo to add these +parts to the sudo configuration. Note that each goes in a separate +part of the overall file, and that we assume below that Tomcat is +running as the user `tavserv`; you will probably need to change (e.g., +to `tomcat` or `nobody`) as appropriate. + +This defines some flags for the main server user: + + Defaults:tavserv !lecture, timestamp_timeout=0, passwd_tries=1 + +This defines a rule for who the server can switch to. Let's say that +they have to be a member of the Unix user group `taverna`; if a user +isn't in that group, they cannot use Taverna Server. (Note that `root` +should not be part of the group!) + + Runas_Alias TAV = %taverna + +This creates the actual permission, saying that the `tavserv` user may +run anything as any user in the alias above (i.e., in the `taverna` +group). The `NOPASSWD` is important because it allows Taverna Server +to do the delegation even when running as a user that can't log in. + + tavserv ALL=(TAV) NOPASSWD: ALL + +### Now, place the WAR into Tomcat's `webapps` directory. + +You may use a filename that relates to what URL you want Taverna Server to +appear at within Tomcat (e.g., if you want it to be deployed at +`/taverna`, rename the WAR to a filename like `webapps/taverna.war`). + +### Finally, start Tomcat. + +Taverna Server should then become available at +the equivalent of http://localhost:8080/taverna-server/ + http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/blob/a5837275/usage.md ---------------------------------------------------------------------- diff --git a/usage.md b/usage.md index ea57dd8..502cb43 100644 --- a/usage.md +++ b/usage.md @@ -55,7 +55,7 @@ Taverna Server exposes some _file access operations_ which are performed on file Associated with each workflow run is a **state**. The state transition diagram is this: - + The blue states are the initial and final states, and all states in *italic* cannot be observed in practice. The black arrows represent automatic state changes, the blue arrows are for manually-triggered transition, and the red arrows are destructions, which can be done from any state (other than the initial unobservable one) and which may be either manually or automatically triggered; automatic destruction happens when the run reaches its expiry time (which you can set but cannot remove). Note that there are two transitions from *Operating* to *Finished*; they are not equivalent. The automatic transition represents the termination of the workflow execution with such outputs produced as are going to be generated, whereas the manual transition is where the execution is killed and outputs may be not generated even if they conceptually existed at that point. Also note that it is only the transition from *Initialized* to *Operating* that represents the start of the workflow execution en gine. @@ -78,23 +78,18 @@ The result is `201 Created` that gives the location of the created run (in a `Lo To set the input port `FOO` to have the string value `BAR`, you would **PUT** to `{RUN_URI}/input/input/FOO` with `application/xml` as content-type: -```xml -<t2sr:runInput xmlns:t2sr="http://ns.taverna.org.uk/2010/xml/server/rest/";> - <t2sr:value>BAR</t2sr:value> -</t2sr:runInput> -``` - + <t2sr:runInput xmlns:t2sr="http://ns.taverna.org.uk/2010/xml/server/rest/";> + <t2sr:value>BAR</t2sr:value> + </t2sr:runInput> *Uploading a File for One Input* The values for an input port can also be set by first creating a file on the server. Thus, if you were staging the value `BAR` to input port `FOO` by means of a file `BOO.TXT` you would first **POST** this message to `{RUN_URI}/wd` as content-type `application/xml` -```xml -<t2sr:upload t2sr:name="BOO.TXT" xmlns:t2sr="http://ns.taverna.org.uk/2010/xml/server/rest/";> - QkFS -</t2sr:upload> -``` + <t2sr:upload t2sr:name="BOO.TXT" xmlns:t2sr="http://ns.taverna.org.uk/2010/xml/server/rest/";> + QkFS + </t2sr:upload> Note that `QkFS` is the base64-encoded form of `BAR` in UTF-8 encoding. Each workflow run has its own working directory on the server for uploaded files are placed; however in the Web API you are never told the name of this working directory. @@ -102,19 +97,15 @@ You can also **PUT** the binary contents of the file (as `application/octet-stre Once you've created the file, you can then set it's relative path as the input for the port by **PUT**ting this message to `{RUN_URI}/input/input/FOO` -```xml -<t2sr:runInput xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/";> - <t2sr:file>BOO.TXT</t2sr:file> -</t2sr:runInput> -``` + <t2sr:runInput xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/";> + <t2sr:file>BOO.TXT</t2sr:file> + </t2sr:runInput> Note the similarity of the final part of this process to the previous method for setting an input, but here using `<t2sr:file>`. You can also create a **directory**, e.g., `IN/`, to hold the input files. This is done by **POST**ing a different message to `{RUN_URI}/wd` -```xml -<t2sr:mkdir t2sr:name="IN" xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/"; /> -``` + <t2sr:mkdir t2sr:name="IN" xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/"; /> With that, you can then create files in the `IN` subdirectory by sending the upload message to `{RUN_URI}/wd/IN` and you can use the files there as input by using relative paths like `IN/BOO.TXT`. You can also create nested sub-directories by sending the `<t2sr:mkdir>` message to the natural URI of the parent directory, just as sending an upload message to that URI creates a file in that directory. @@ -122,13 +113,11 @@ With that, you can then create files in the `IN` subdirectory by sending the upl You can use an existing file attached to a workflow run *on the same server*, provided you have read permission to access that run. You do this by using a **PUT** to set the input to a _reference_ (the actual URL below is just an example copying from run `78c7a1fd-f794-4db3-914a-ec70731d9928`; the must be the **full URL** to the file): -```xml -<t2sr:runInput xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/";> - <t2sr:reference> - http://localhost:8080/taverna-server/rest/runs/78c7a1fd-f794-4db3-914a-ec70731d9928/wd/file.name - </t2sr:reference> -</t2sr:runInput> -``` + <t2sr:runInput xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/";> + <t2sr:reference> + http://localhost:8080/taverna-server/rest/runs/78c7a1fd-f794-4db3-914a-ec70731d9928/wd/file.name + </t2sr:reference> + </t2sr:runInput> The data will be copied across efficiently into a run-local file. This version of Taverna Server does not support accessing files stored on any other server or on the general web via this mechanism. @@ -143,17 +132,15 @@ The final way of setting up the inputs to a workflow is to upload (using the sam To set a username and password for a service, you would **POST** to `{RUN_URI}/security/credentials` a message like this (assuming that the WSDL address is `https://example.com/serv.wsdl`, that the username to use is `fred123`, and that the password is `ThePassWord`): -```xml -<t2sr:credential - xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/"; - xmlns:t2s="http://ns.taverna.org.uk/2010/xml/server/";> - <t2s:userpass> - <t2s:serviceURI>https://example.com/serv.wsdl</t2s:serviceURI> - <t2s:username>fred123</t2s:username> - <t2s:password>ThePassWord</t2s:password> - </t2s:userpass> -</t2sr:credential> -``` + <t2sr:credential + xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/"; + xmlns:t2s="http://ns.taverna.org.uk/2010/xml/server/";> + <t2s:userpass> + <t2s:serviceURI>https://example.com/serv.wsdl</t2s:serviceURI> + <t2s:username>fred123</t2s:username> + <t2s:password>ThePassWord</t2s:password> + </t2s:userpass> + </t2sr:credential> (Notice the different `t2s` namespace) @@ -171,16 +158,14 @@ _There is a fourth state, `Stopped`, but it is not yet supported._ Thus, if a single output `FOO.OUT` was produced from the workflow, it would be written to the file that can be retrieved from `{RUN_URI}/wd/out/FOO.OUT` and the result of the **GET** on `{RUN_URI}/wd/out` would look something like this: -```xml -<t2sr:directoryContents - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns:t2s="http://ns.taverna.org.uk/2010/xml/server/"; - xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/";> - <t2s:file - xlink:href="http://localhost:8080/taverna-server/rest/runs/78c7a1fd-f794-4db3-914a-ec70731d9928/wd/out/FOO.OUT"; - t2sr:name="FOO.OUT">out/FOO.OUT</t2s:file> -</t2sr:directoryContents> -``` + <t2sr:directoryContents + xmlns:xlink="http://www.w3.org/1999/xlink"; + xmlns:t2s="http://ns.taverna.org.uk/2010/xml/server/"; + xmlns:t2sr= "http://ns.taverna.org.uk/2010/xml/server/rest/";> + <t2s:file + xlink:href="http://localhost:8080/taverna-server/rest/runs/78c7a1fd-f794-4db3-914a-ec70731d9928/wd/out/FOO.OUT"; + t2sr:name="FOO.OUT">out/FOO.OUT</t2s:file> + </t2sr:directoryContents> 9. The standard output and standard error from the T2 Command Line Executor subprocess can be read via properties of the special I/O listener. To do that, do a **GET** on `{RUN_URI}/listeners/io/properties/stdout` (or `stderr`). Once the subprocess has finished executing, the I/O listener will provide a third property containing the exit code of the subprocess, called `exitcode`. @@ -197,18 +182,16 @@ API of the REST Interface Note that examples in this document are actually pseudo-schemas. For example, this shows how the various marks on attributes and elements indicate their cardinality and type: -```xml -<element requiredAttr="xsd:someType"> - <requiredChildElement /> - <zeroOrMoreChildren /> * - <optionalChild /> ? - <alternative1 /> | <alternative2 /> - <childWithSimpleStringContent> - xsd:string - </childWithSimpleStringContent> - <childWithUndescribedContent ... /> -</element> -``` + <element requiredAttr="xsd:someType"> + <requiredChildElement /> + <zeroOrMoreChildren /> * + <optionalChild /> ? + <alternative1 /> | <alternative2 /> + <childWithSimpleStringContent> + xsd:string + </childWithSimpleStringContent> + <childWithUndescribedContent ... /> + </element> To be exact, a suffix of `*` marks an element that can be repeated arbitrarily often, a suffix of `?` marks an optional element or attribute (either present or absent); and otherwise exactly one of the element is required (or, for attributes, the attribute must be present). We never use cardinalities other than these, and _order_ is always respected. Where there is complex content, it will either be described inline or separately. Where there is a choice between two elements, they are separated by a `|` character. @@ -248,17 +231,15 @@ It is important to use the right namespaces for their corresponding elements/att Retrieves a description of the server as either XML or JSON (determined by content negotiation) that indicates other locations to find sub-resources. -```xml -<t2sr:serverDescription - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string" > - - <t2sr:runs xlink:href="xsd:anyURI" /> - <t2sr:policy xlink:href="xsd:anyURI" /> - <t2sr:feed xlink:href="xsd:anyURI" /> -</t2sr:serverDescription> -``` + <t2sr:serverDescription + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string" > + + <t2sr:runs xlink:href="xsd:anyURI" /> + <t2sr:policy xlink:href="xsd:anyURI" /> + <t2sr:feed xlink:href="xsd:anyURI" /> + </t2sr:serverDescription> The `<t2sr:feed>` element is a pointer to the location of the Atom feed for events issued to the user about things like the termination of their workflows. @@ -271,11 +252,9 @@ The `<t2sr:feed>` element is a pointer to the location of the Atom feed for even Retrieve a list of all runs that the current user can see, as XML or JSON. Note that the user will not be told about runs that they are not permitted to see (i.e., that they didnât create and havenât been given permission to see). Deleted runs will also not be present. -```xml -<t2sr:runList> - <t2sr:run xlink:href="xsd:anyURI" /> * -</t2sr:runList> -``` + <t2sr:runList> + <t2sr:run xlink:href="xsd:anyURI" /> * + </t2sr:runList> * Method: POST * Consumes: `application/vnd.taverna.t2flow+xml`, `application/xml` @@ -284,11 +263,9 @@ Retrieve a list of all runs that the current user can see, as XML or JSON. Note Accepts (or not) a request to create a new run executing the given workflow. **The content should normally be a t2flow workflow document with the t2flow content type** `application/vnd.taverna.t2flow+xml`, but when the content type is `application/xml`, the workflow must be wrapped (in an XML infoset sense) inside an `<t2s:workflow>` element. -```xml -<t2s:workflow> - <t2flow:workflow ... /> -</t2s:workflow> -``` + <t2s:workflow> + <t2flow:workflow ... /> + </t2s:workflow> Care should be taken to handle t2flow namespaces for the `application/xml` approach. @@ -304,19 +281,17 @@ The result will be a HTTP `201 Created` redirect (via `Location` HTML header) to Describe the (public) parts of the policies of this server, as XML or JSON. -```xml -<t2sr:policyDescription - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string" > - - <t2sr:runLimit xlink:href="xsd:anyURI" /> - <t2sr:permittedWorkflows xlink:href="xsd:anyURI" /> - <t2sr:permittedListeners xlink:href="xsd:anyURI" /> - <t2sr:enabledNotificationFabrics xlink:href="xsd:anyURI" /> - <t2sr:capabilities xlink:href="xsd:anyURI" /> -</t2sr:policyDescription> -``` + <t2sr:policyDescription + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string" > + + <t2sr:runLimit xlink:href="xsd:anyURI" /> + <t2sr:permittedWorkflows xlink:href="xsd:anyURI" /> + <t2sr:permittedListeners xlink:href="xsd:anyURI" /> + <t2sr:enabledNotificationFabrics xlink:href="xsd:anyURI" /> + <t2sr:capabilities xlink:href="xsd:anyURI" /> + </t2sr:policyDescription> #### Resource: /policy/capabilities @@ -415,38 +390,36 @@ Note that all of these resources require that the user be authenticated and perm Describes the sub-resources associated with this workflow run, as XML or JSON. -```xml -<t2sr:runDescription - t2sr:owner="xsd:string" - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string" > - - <t2sr:expiry xlink:href="xsd:anyURI"> - xsd:string - </t2sr:expiry> - <t2sr:creationWorkflow xlink:href="xsd:anyURI" /> - <t2sr:createTime xlink:href="xsd:anyURI" /> - <t2sr:startTime xlink:href="xsd:anyURI" /> - <t2sr:finishTime xlink:href="xsd:anyURI" /> - <t2sr:status xlink:href="xsd:anyURI" /> - <t2sr:workingDirectory xlink:href="xsd:anyURI" /> - <t2sr:inputs xlink:href="xsd:anyURI" /> - <t2sr:output xlink:href="xsd:anyURI" /> - <t2sr:securityContext xlink:href="xsd:anyURI" /> - <t2sr:listeners xlink:href="xsd:anyURI"> - <t2sr:listener xlink:href="xsd:anyURI" /> * - </t2sr:listeners> - <t2sr:interaction xlink:href="xsd:anyURI" /> - <t2sr:name xlink:href="xsd:anyURI" /> - <t2sr:stdout xlink:href="xsd:anyURI" /> - <t2sr:stderr xlink:href="xsd:anyURI" /> - <t2sr:usage xlink:href="xsd:anyURI" /> - <t2sr:log xlink:href="xsd:anyURI" /> - <t2sr:run-bundle xlink:href="xsd:anyURI" /> - <t2sr:generate-provenance xlink:href="xsd:anyURI" /> -</t2sr:runDescription> -``` + <t2sr:runDescription + t2sr:owner="xsd:string" + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string" > + + <t2sr:expiry xlink:href="xsd:anyURI"> + xsd:string + </t2sr:expiry> + <t2sr:creationWorkflow xlink:href="xsd:anyURI" /> + <t2sr:createTime xlink:href="xsd:anyURI" /> + <t2sr:startTime xlink:href="xsd:anyURI" /> + <t2sr:finishTime xlink:href="xsd:anyURI" /> + <t2sr:status xlink:href="xsd:anyURI" /> + <t2sr:workingDirectory xlink:href="xsd:anyURI" /> + <t2sr:inputs xlink:href="xsd:anyURI" /> + <t2sr:output xlink:href="xsd:anyURI" /> + <t2sr:securityContext xlink:href="xsd:anyURI" /> + <t2sr:listeners xlink:href="xsd:anyURI"> + <t2sr:listener xlink:href="xsd:anyURI" /> * + </t2sr:listeners> + <t2sr:interaction xlink:href="xsd:anyURI" /> + <t2sr:name xlink:href="xsd:anyURI" /> + <t2sr:stdout xlink:href="xsd:anyURI" /> + <t2sr:stderr xlink:href="xsd:anyURI" /> + <t2sr:usage xlink:href="xsd:anyURI" /> + <t2sr:log xlink:href="xsd:anyURI" /> + <t2sr:run-bundle xlink:href="xsd:anyURI" /> + <t2sr:generate-provenance xlink:href="xsd:anyURI" /> + </t2sr:runDescription> * Method: DELETE * Consumes: N/A @@ -534,18 +507,15 @@ Gives the workflow document used to create the workflow run, as raw t2flow, wrap Describe the sub-URIs relating to workflow inputs. - -```xml -<t2sr:runInputs - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string" > - - <t2sr:expected xlink:href="xsd:anyURI" /> - <t2sr:baclava xlink:href="xsd:anyURI" /> - <t2sr:input xlink:href="xsd:anyURI" /> * -</t2sr:runInputs> -``` + <t2sr:runInputs + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string" > + + <t2sr:expected xlink:href="xsd:anyURI" /> + <t2sr:baclava xlink:href="xsd:anyURI" /> + <t2sr:input xlink:href="xsd:anyURI" /> * + </t2sr:runInputs> #### Resource: /runs/{id}/input/baclava @@ -572,20 +542,18 @@ Sets the Baclava file describing the inputs. The name is relative to the main wo Describe the *expected* inputs of this workflow run. They must be supplied by either per-input specifications or by the baclava file. -```xml -<port:inputDescription - port:workflowId="xsd:string" - port:workflowRun="xsd:anyURI" - port:workflowRunId="xsd:string"> - -<port:input - port:name="xsd:string" - port:depth="xsd:int" ? - xlink:href="xsd:anyURI" ?> -</port:input> * - -</port:inputDescription> -``` + <port:inputDescription + port:workflowId="xsd:string" + port:workflowRun="xsd:anyURI" + port:workflowRunId="xsd:string"> + + <port:input + port:name="xsd:string" + port:depth="xsd:int" ? + xlink:href="xsd:anyURI" ?> + </port:input> * + + </port:inputDescription> #### Resource: /runs/{id}/input/input/{name} @@ -596,17 +564,15 @@ Describe the *expected* inputs of this workflow run. They must be supplied by ei Gives a description of what is used to supply a particular input, which will be either a literal value or the name of a file in the working directory or a reference to a file maintained by another workflow run on the same server (which will be copied efficiently if the user has permission). -```xml -<t2sr:runInput t2sr:name="xsd:string" t2s:serverVersion="xsd:string" t2s:serverRevision="xsd:string" t2s:serverBuildTimestamp="xsd:string" > - - <t2sr:file> xsd:string </t2sr:file> -| - <t2sr:reference> xsd:anyURI </t2sr:reference> -| - <t2sr:value> xsd:string </t2sr:value> - -</t2sr:runInput> -``` + <t2sr:runInput t2sr:name="xsd:string" t2s:serverVersion="xsd:string" t2s:serverRevision="xsd:string" t2s:serverBuildTimestamp="xsd:string" > + + <t2sr:file> xsd:string </t2sr:file> + | + <t2sr:reference> xsd:anyURI </t2sr:reference> + | + <t2sr:value> xsd:string </t2sr:value> + + </t2sr:runInput> * Method: PUT @@ -627,40 +593,38 @@ Gives a description of the outputs (in XML or JSON) as currently understood. Not -```xml -<port:workflowOutputs - port:workflowId="xsd:string" - port:workflowRun="xsd:anyURI" - port:workflowRunId="xsd:string"> - - <port:output - port:name="xsd:string" - port:depth="xsd:int" ? > - - <port:value - xlink:href="xsd:anyURI" ? - port:fileName="xsd:string" - port:contentType="xsd:string" - port:byteLength="xsd:int" /> - | - <port:list - xlink:href="xsd:anyURI" ? - port:length="xsd:int" ? > - - <!-- Sequence of values, just as for a port --> - </port:list> - | - <port:error - xlink:href="xsd:anyURI" ? - port:depth="xsd:int" ? /> - | - <port:absent - xlink:href="xsd:anyURI" ? /> - -</port:output> * - -</port:workflowOutputs> -``` + <port:workflowOutputs + port:workflowId="xsd:string" + port:workflowRun="xsd:anyURI" + port:workflowRunId="xsd:string"> + + <port:output + port:name="xsd:string" + port:depth="xsd:int" ? > + + <port:value + xlink:href="xsd:anyURI" ? + port:fileName="xsd:string" + port:contentType="xsd:string" + port:byteLength="xsd:int" /> + | + <port:list + xlink:href="xsd:anyURI" ? + port:length="xsd:int" ? > + + <!-- Sequence of values, just as for a port --> + </port:list> + | + <port:error + xlink:href="xsd:anyURI" ? + port:depth="xsd:int" ? /> + | + <port:absent + xlink:href="xsd:anyURI" ? /> + + </port:output> * + + </port:workflowOutputs> * Method: GET * Consumes: N/A @@ -748,32 +712,30 @@ The current implementation does not permit installing new listeners, and comes w **GET** a list of the listeners installed in the workflow run. -```xml -<t2sr:listeners - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string" > - - <t2sr:listener xlink:href="xsd:anyURI" - t2sr:name="xsd:string" - t2sr:type="xsd:string" - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string"> - - <t2sr:configuration xlink:href="xsd:anyURI" /> - - <t2sr:properties> - <t2sr:property - xlink:href="xsd:anyURI" - t2sr:name="xsd:string"> - </t2sr:property> * - </t2sr:properties> - - </t2sr:listener> * - -</t2sr:listeners> -``` + <t2sr:listeners + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string" > + + <t2sr:listener xlink:href="xsd:anyURI" + t2sr:name="xsd:string" + t2sr:type="xsd:string" + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string"> + + <t2sr:configuration xlink:href="xsd:anyURI" /> + + <t2sr:properties> + <t2sr:property + xlink:href="xsd:anyURI" + t2sr:name="xsd:string"> + </t2sr:property> * + </t2sr:properties> + + </t2sr:listener> * + + </t2sr:listeners> * Method: POST @@ -784,12 +746,9 @@ The current implementation does not permit installing new listeners, and comes w Add a new event listener to the named workflow run of the given type and under the conditions imposed by the contents of the configuration document (the body of the element). Note that the configuration cannot be changed after creation. -```xml - -<t2sr:listenerDefinition t2sr:type="xsd:string"> - xsd:string -</t2sr:listenerDefinition> -``` + <t2sr:listenerDefinition t2sr:type="xsd:string"> + xsd:string + </t2sr:listenerDefinition> #### Resource: /runs/{id}/listeners/{name} @@ -800,26 +759,24 @@ Add a new event listener to the named workflow run of the given type and under t **GET** the description of a particular listener attached to a workflow run. -```xml -<t2sr:listener - xlink:href="xsd:anyURI" - t2sr:name="xsd:string" - t2sr:type="xsd:string" - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string"> - - <t2sr:configuration xlink:href="xsd:anyURI" /> - - <t2sr:properties> - <t2sr:property + <t2sr:listener xlink:href="xsd:anyURI" - t2sr:name="xsd:string" /> - </t2sr:property> * - </t2sr:properties> - -</t2sr:listener> -``` + t2sr:name="xsd:string" + t2sr:type="xsd:string" + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string"> + + <t2sr:configuration xlink:href="xsd:anyURI" /> + + <t2sr:properties> + <t2sr:property + xlink:href="xsd:anyURI" + t2sr:name="xsd:string" /> + </t2sr:property> * + </t2sr:properties> + + </t2sr:listener> #### Resource: /runs/{id}/listeners/{name}/configuration @@ -840,14 +797,12 @@ Add a new event listener to the named workflow run of the given type and under t **GET** the list of properties supported by a given event listener attached to a workflow run. -```xml -<t2sr:properties> - <t2sr:property - xlink:href="xsd:anyURI" - t2sr:name="xsd:string"> - <t2sr:property> * -</t2sr:properties> -``` + <t2sr:properties> + <t2sr:property + xlink:href="xsd:anyURI" + t2sr:name="xsd:string"> + <t2sr:property> * + </t2sr:properties> #### Resource: /runs/{id}/listeners/{name}/properties/{propName} @@ -870,33 +825,31 @@ Set the value of the particular property of an event listener attached to a work * Method: GET * Consumes: N/A -* Produces: `application/xml`, application/json +* Produces: `application/xml`, `application/json` * Response codes: `200 OK` Gives a description of the security information supported by the workflow run. -```xml -<t2sr:securityDescriptor - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string"> - - <t2sr:owner> - xsd:string - </t2sr:owner> - <t2sr:permissions xlink:href="xsd:anyURI" /> - - <t2sr:credentials xlink:href="xsd:anyURI"> - <t2sr:credential> ... </t2sr:credential> * - </t2sr:credentials> - - <t2sr:trusts xlink:href="xsd:anyURI"> - <t2sr:trust> ... </t2sr> * - </t2sr:trusts> - -</t2sr:securityDescriptor> -``` - + <t2sr:securityDescriptor + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string"> + + <t2sr:owner> + xsd:string + </t2sr:owner> + <t2sr:permissions xlink:href="xsd:anyURI" /> + + <t2sr:credentials xlink:href="xsd:anyURI"> + <t2sr:credential> ... </t2sr:credential> * + </t2sr:credentials> + + <t2sr:trusts xlink:href="xsd:anyURI"> + <t2sr:trust> ... </t2sr> * + </t2sr:trusts> + + </t2sr:securityDescriptor> + #### Resource: /runs/{id}/security/credentials @@ -907,22 +860,20 @@ Gives a description of the security information supported by the workflow run. Gives a list of credentials supplied to this workflow run. -```xml -<t2sr:credentials - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string"> - - <t2s:userpass xlink:href="xsd:anyURI"> - .. - </t2s:userpass> * - - <t2s:keypair xlink:href="xsd:anyURI"> - .. - </t2s:keypair> * - -</t2sr:credentials> -``` + <t2sr:credentials + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string"> + + <t2s:userpass xlink:href="xsd:anyURI"> + .. + </t2s:userpass> * + + <t2s:keypair xlink:href="xsd:anyURI"> + .. + </t2s:keypair> * + + </t2sr:credentials> For more description of the contents of the `<t2s:userpass>` and `<t2s:keypair>` elements, see below. @@ -936,35 +887,31 @@ Creates a new credential. Multiple types supported. Note that none of these shou Password credential `<t2s:userpass>`: -```xml -<t2s:userpass> - <ts2:serviceURI>xsd:anyURI</t2s:serviceURI> - <t2s:username>xsd:string</t2s:username> - <t2s:password>xsd:string</t2s:password> -</t2s:userpass> -``` + <t2s:userpass> + <ts2:serviceURI>xsd:anyURI</t2s:serviceURI> + <t2s:username>xsd:string</t2s:username> + <t2s:password>xsd:string</t2s:password> + </t2s:userpass> Key credential `<t2s:keypair>`: -```xml -<t2s:keypair> - - <ts2:serviceURI>xsd:anyURI</t2s:serviceURI> - - <t2s:credentialName>xsd:string</t2s:credentialName> - - <t2s:credentialFile>xsd:string</t2s:credentialFile> ? - - <t2s:fileType>xsd:string</t2s:fileType> ? - - <t2s:unlockPassword>xsd:string</t2s:unlockPassword> ? - - <t2s:credentialBytes> - xsd:base64Binary - </t2s:credentialBytes> ? - -</t2s:keypair> -``` + <t2s:keypair> + + <ts2:serviceURI>xsd:anyURI</t2s:serviceURI> + + <t2s:credentialName>xsd:string</t2s:credentialName> + + <t2s:credentialFile>xsd:string</t2s:credentialFile> ? + + <t2s:fileType>xsd:string</t2s:fileType> ? + + <t2s:unlockPassword>xsd:string</t2s:unlockPassword> ? + + <t2s:credentialBytes> + xsd:base64Binary + </t2s:credentialBytes> ? + + </t2s:keypair> Note that one of the `<t2s:credentialFile>` and `<t2s:credentialBytes>` elements should be supplied, but not both. @@ -1016,22 +963,19 @@ Gives the identity of who owns the workflow run. Gives a list of all non-default permissions associated with the enclosing workflow run. By default, nobody has any access at all except for the owner of the run. - -```xml -<t2sr:permissionsDescriptor - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string"> - - <t2sr:permission xlink:href="xsd:anyURI"> - <t2sr:userName> xsd:string </t2sr:userName> - <t2sr:permission> - none | read | update | destroy - </t2sr:permission> - </t2sr:permission> * - -</t2sr:permissionsDescriptor> -``` + <t2sr:permissionsDescriptor + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string"> + + <t2sr:permission xlink:href="xsd:anyURI"> + <t2sr:userName> xsd:string </t2sr:userName> + <t2sr:permission> + none | read | update | destroy + </t2sr:permission> + </t2sr:permission> * + + </t2sr:permissionsDescriptor> * Method: POST * Consumes: `application/xml`, `application/json` @@ -1041,14 +985,12 @@ Gives a list of all non-default permissions associated with the enclosing workfl Creates a new assignment of permissions to a particular user. -```xml -<t2sr:permissionUpdate> - <t2sr:userName> xsd:string </t2sr:userName> - <t2sr:permission> - none|read|update|destroy - </t2sr:permission> -</t2sr:permissionUpdate> -``` + <t2sr:permissionUpdate> + <t2sr:userName> xsd:string </t2sr:userName> + <t2sr:permission> + none|read|update|destroy + </t2sr:permission> + </t2sr:permissionUpdate> #### Resource: /runs/{id}/security/permissions/{user} @@ -1083,22 +1025,20 @@ Deletes (by resetting to default, i.e., `none`) the permissions associated with Gives a list of trusted identities supplied to this workflow run. -```xml -<t2sr:trustedIdentities - t2s:serverVersion="xsd:string" - t2s:serverRevision="xsd:string" - t2s:serverBuildTimestamp="xsd:string"> - <t2sr:trust xlink:href="xsd:anyURI"> - <t2s:certificateFile> - xsd:string - </t2s:certificateFile> ? - <t2s:fileType> xsd:string </t2s:fileType> ? - <t2s:certificateBytes> - xsd:base64Binary - </t2s:certificateBytes> ? - </t2sr:trust> * -</t2sr:trustedIdentities> -``` + <t2sr:trustedIdentities + t2s:serverVersion="xsd:string" + t2s:serverRevision="xsd:string" + t2s:serverBuildTimestamp="xsd:string"> + <t2sr:trust xlink:href="xsd:anyURI"> + <t2s:certificateFile> + xsd:string + </t2s:certificateFile> ? + <t2s:fileType> xsd:string </t2s:fileType> ? + <t2s:certificateBytes> + xsd:base64Binary + </t2s:certificateBytes> ? + </t2sr:trust> * + </t2sr:trustedIdentities> * Method: POST * Consumes: `application/xml`, `application/json` @@ -1107,15 +1047,13 @@ Gives a list of trusted identities supplied to this workflow run. Adds a new trusted identity. The `xlink:href` attribute of the `trust` element will be ignored if supplied, and one of `certificateFile` and `certificateBytes` should be supplied. The `fileType` can normally be omitted, as it is assumed to be X.509 by default (the only type seen in practice). -```xml -<t2sr:trust> - <t2s:certificateFile> xsd:string </t2s:certificateFile> ? - <t2s:fileType> xsd:string </t2s:fileType> ? - <t2s:certificateBytes> - xsd:base64Binary - </t2s:certificateBytes> ? -</t2sr:trust> -``` + <t2sr:trust> + <t2s:certificateFile> xsd:string </t2s:certificateFile> ? + <t2s:fileType> xsd:string </t2s:fileType> ? + <t2s:certificateBytes> + xsd:base64Binary + </t2s:certificateBytes> ? + </t2sr:trust> * Method: DELETE * Consumes: N/A @@ -1133,15 +1071,13 @@ Deletes all trusted identities. Describes a particular trusted identity. -```xml -<t2sr:trust xlink:href="xsd:anyURI"> - <t2s:certificateFile> xsd:string </t2s:certificateFile> ? - <t2s:fileType> xsd:string </t2s:fileType> ? - <t2s:certificateBytes> - xsd:base64Binary - </t2s:certificateBytes> ? -</t2sr:trust> -``` + <t2sr:trust xlink:href="xsd:anyURI"> + <t2s:certificateFile> xsd:string </t2s:certificateFile> ? + <t2s:fileType> xsd:string </t2s:fileType> ? + <t2s:certificateBytes> + xsd:base64Binary + </t2s:certificateBytes> ? + </t2sr:trust> * Method: PUT * Consumes: `application/xml`, `application/json` @@ -1151,15 +1087,13 @@ Describes a particular trusted identity. Updates (i.e., replaces) a particular trusted identity. The *xlink:href* attribute will be ignored if supplied. The *fileType* can normally be omitted, as it is assumed to be X.509 by default (the only type seen in practice). -```xml -<t2sr:trust> - <t2s:certificateFile> xsd:string </t2s:certificateFile> ? - <t2s:fileType> xsd:string </t2s:fileType> ? - <t2s:certificateBytes> - xsd:base64Binary - </t2s:certificateBytes> ? -</t2sr:trust> -``` + <t2sr:trust> + <t2s:certificateFile> xsd:string </t2s:certificateFile> ? + <t2s:fileType> xsd:string </t2s:fileType> ? + <t2s:certificateBytes> + xsd:base64Binary + </t2s:certificateBytes> ? + </t2sr:trust> * Method: DELETE * Consumes: N/A @@ -1183,16 +1117,14 @@ Note that everything following the `/wd` is the path beneath the working directo Gives a description of the working directory or a named directory in or beneath the working directory of the workflow run. The contents of the `dir` and `file` elements are the equivalent pathname (for use in the SOAP interface or to be appended to `â¦/wd` to generate a URI). -```xml -<t2sr:directoryContents> - <t2s:dir xlink:href="xsd:anyURI" t2s:name="xsd:string"> - xsd:string - </t2s:dir> * - <t2s:file xlink:href="xsd:anyURI" t2s:name="xsd:string"> - xsd:string - </t2s:file> * -</t2sr:directoryContents> -``` + <t2sr:directoryContents> + <t2s:dir xlink:href="xsd:anyURI" t2s:name="xsd:string"> + xsd:string + </t2s:dir> * + <t2s:file xlink:href="xsd:anyURI" t2s:name="xsd:string"> + xsd:string + </t2s:file> * + </t2sr:directoryContents> * Method: GET @@ -1223,18 +1155,15 @@ Creates a file or replaces the contents of a file with the given bytes. * Consumes: `application/xml`, `application/json` * Produces: N/A * Response codes: `201 Created` -* Notes: This only applies to directories. The `Location`*` header says what was made. +* Notes: This only applies to directories. The `Location` header says what was made. Creates a directory in the filesystem beneath the working directory of the workflow run, or creates or updates a file's contents, where that file is in or below the working directory of a workflow run. The location that this is POSTed to determines what the parent directory of the created entity is, and the `name` attribute determines its name. The operation done depends on the element passed, which should be one of these: - -```xml -<t2sr:mkdir t2sr:name="xsd:string" /> - -<t2sr:upload t2sr:name="xsd:string"> - xsd:base64Binary -</t2sr:upload> -``` + <t2sr:mkdir t2sr:name="xsd:string" /> + + <t2sr:upload t2sr:name="xsd:string"> + xsd:base64Binary + </t2sr:upload> Note that the *upload* operation is deprecated; directly PUTting the data is preferred, as that has no size restrictions.
