UNDER CONSTRUCTION
This document only addresses:
1. Web services directory structure that is being deployed by DSPS
Below is the directory structure that is currently being deployed by DSPS.
2. Web services system environmental variable and its related configuration files
WSETCDIR is a system environmental variable and a JVM property that contains the directory path to the 'root' of the web services directory structure. The $WSETCDIR root directory contains 2 properties files, webserviceConfig.properties and mastermanagement.properties, and are described below:
webserviceConfiguration.property file
File name |
webserviceConfig.properties |
Path |
$WSETCDIR/webserviceConfig.properties |
Type |
Java properties file |
Description |
This file contains the directory paths that is used by a web service to access to access resources that it needs. See the Directory Structure above. |
The syntax of each entry of this file is:
<key>=<directory path>
Where <key> can be any of the following:
key |
description |
logsdir |
path to where the web service log files are to be stored. This keyword is required. |
basedir |
this the directory under which all other web service directories and files are found. This must correspond to the value of the environmental variable $WSETCDIR. This keyword is required. |
containersdir |
path to the containers directory. This keyword is required. |
keystoredir |
path to the keystore directory. This keyword is required. |
jmxmastermanagement |
path to the mastermanagement.properties file. This keyword is required. |
applicationcertificatejks |
path to the application certificate java keystore that is used by JMX. This keyword is required. |
servertruststorejks |
path to the trusted servers java keystore that is used by JMX. This keyword is required. |
When specifying the path, the path must be explicated defined. Do not use the environmental variable. Below is an example. Assume that $WSETCDIR contains /usr/local/etc/map/ws.
logsdir=/usr/local/etc/map/ws/logs
basedir=/usr/local/etc/map/ws
containersdir=/usr/local/etc/map/ws/containers
keystoredir=/usr/local/etc/map/ws/keystore
jmxdir=/usr/local/etc/map/ws/jmx
krbdir=/usr/local/etc/map/ws/krb
jmxmastermanagement=/usr/local/etc/map/ws/mastermanagement.properties
applicationcertificatejks=/usr/local/etc/map/ws/keystore/mapping.app.mit.edu.jks
servertruststorejks=/usr/local/etc/map/ws/keystore/serverTrustStore.jks
In the above, mapping.app.mit.edu.jks is the application certificate keystore and serverTrustStore.jks is the trusted server keystore.
File name |
mastermanagement.properties |
Path |
$WSETCDIR/mastermanagement.properties |
Type |
Java properties file |
Description |
This file contains the Tomcat container/JMX port mapping. The properties file is configured and deployed by DSPS. |
No further description of this file will be provided other than to say that the mastermanagement.properties file is auto generated and should not be modified.
3. Web services system environmental variable and its related sub-directories
Below is a description of the $WSETCDIR sub-directories as shown is section 1.
Directory |
jmx |
Path |
$WSETCDIR/jmx |
Type |
directory |
Description |
The jmx directory contains the jmxremote.access and the jmxremote.password files. Both of these files are used by the web services to control remote JMX access to the various Tomcat container MBean servers. These 2 files must be present and configured on all machines which have DSPS supported web services installed. |
Directory |
krb |
Path |
$WSETCDIR/krb |
Type |
directory |
Description |
The krb directory contains the keytab files that are used by the web services. |
Directory |
keystore |
Path |
$WSETCDIR/keystore |
Type |
directory |
Description |
The keystore directory contains the mapping.app.mit.edu.jks and the serverTrustStore.jks Java keystores. Both of the keystore files (.jks files) are used by JMX and must be present and configured on all machines which have DSPS supported web services installed. |
Directory |
logs |
Path |
$WSETCDIR/logs |
Type |
directory |
Description |
The logs directory contains the log files that are generated the web services. |
Directory |
containers |
Path |
$WSETCDIR/containers |
Type |
directory |
Description |
The containers directory contains information relative to the various Tomcat containers and web services. Currently there are 5 Tomcat containers. The Tomcat container names are: default, mitid, moira, roles and misc. Corresponding to each Tomcat container there is a sub-directory under the containers directory with an identical name. See the Section 1 above |
4. the containers directory
This section contains a description of the subdirectories (and associated files) under the $WSETCDIR/containers directory. There are currently 5 sub-directories directly under the containers directory. These sub-directories are default, mitid, moira, roles and misc and are described below:
the default directory:
The default directory corresponds to the Tomcat default container and contains sub-directories what represents the web services which have been deployed to the default Tomcat container. Currently there is only 1 web service deployed to the default Tomcat container. The context name of the web service is defltws. This means that the default directory contains a sub-directory who's name is defltws (see Section 1).
The defltws directory contains only 1 editable configuration file (allowedLocations.properties) and is described below. All other files and directories are automatically created and maintained by the defltws web services. DO NOT EDIT THESE FILES.
allowedLocations.properties file
name |
allowedLocations.properties |
path |
$WSETCDIR/containers/default/defltws/allowedLocations.properties |
type |
Java properties file |
format |
<x509 application certificat CN>=<key value>, <key value>... |
description |
This property file is used to control access to the defltws web service and contains the CNs of all the x509 application certificates that are allowed to the defltws web service |
allowable <key value> values |
description |
allowlogging |
this key work will enable the web service to do transaction logging. If not used, transaction logging is turned off. |
nombean |
this key word will turn off JMX logging. If not used, JMX logging is turned on |
EXAMPLE 1: mycert.app.mit.edu=allowlogging, nombean
In the example 1, the x509 application certificate CN is mycert.app.mit.edu; transaction logging is turned on; JMX logging is turned off.
EXAMPLE 2: mapping.app.mit.edu=
In the example 2, the x509 application certificate CN is mapping.app.mit.edu; transaction logging is turned off; JMX logging is turned on.
EXAMPLE 3: reg.app.mit.edu=nombean
In the example 3, the x509 application certificate CN is reg.app.mit.edu; transaction logging is turned off; JMX logging is turned off.
the mitid directory:
The mitid directory corresponds to the Tomcat mitid container and contains sub-directories what represents the web services which have been deployed to the mitid Tomcat container. Currently there is only 1 web service deployed to the mitid Tomcat container. The context name of the web service is mitidws. This means that the mitid directory contains a sub-directory who's name is mitidws (see Section 1).
The mitidws directory contains 2 editable configuration files (allowLocations.properties and mitidws.properties) each of which is described below: All other files and directories are automatically created and maintained by the mitidws web services. DO NOT EDIT THESE FILES.
allowedLocations.properties file
name |
allowedLocations.properties |
path |
$WSETCDIR/containers/mitid/mitidws/allowedLocations.properties |
type |
Java properties file |
format |
<x509 application certificat CN>=<key value>, <key value>... |
description |
This property file is used to control access to the defltws web service and contains the CNs of all the x509 application certificates that are allowed to the mitidwsweb service |
allowable <key value> values |
description |
allowlogging |
this key work will enable the web service to do transaction logging. If not used, transaction logging is turned off. |
nombean |
this key word will turn off JMX logging. If not used, JMX logging is turned on |
EXAMPLE 1: mycert.app.mit.edu=allowlogging, nombean
In the example 1, the x509 application certificate CN is mycert.app.mit.edu; transaction logging is turned on; JMX logging is turned off.
EXAMPLE 2: mapping.app.mit.edu=
In the example 2, the x509 application certificate CN is mapping.app.mit.edu; transaction logging is turned off; JMX logging is turned on.
EXAMPLE 3: reg.app.mit.edu=nombean
In the example 3, the x509 application certificate CN is reg.app.mit.edu; transaction logging is turned off; JMX logging is turned off.
mitidws.properties file
name |
mitidws.properties |
path |
$WSETCDIR/containers/mitid/mitidws/mitidws.properties |
type |
Java properties file |
format |
<key>=<key value> |
description |
The MIT ID servers require Kerberos authentication. This property file is used to configure the mitidws to use Kerberos. |
allowable <key> values |
<key value> description |
kerberosCache |
path to and name of the Kerberos ticket cache that will be used by mitidws. This is a file based cache. This is an optional key word. It this key word is not used, the default will be FILE:/tmp/krb5cc_mitidws. |
kerberosKeytab |
path to and name of the server's keytab file. This is a required key word. |
EXAMPLE 1:
kerberosCache=FILE:/local/cache/mitidws_cache
kerberosKeytab=/home/www/etc/krb/development.krb5.keytab host/development.mit.edu@ATHENA.MIT.EDU.
In the example 1, the Kerberos cache name is mitidws_cache and will be created in the directory /local/cache directory. The keytab file is development.krb5.keytab and is located in the /home/www/etc/krb directory. The kerberos principal of the keytab is host/development.mit.edu@ATHENA.MIT.EDU.
EXAMPLE 2:
kerberosKeytab=/user/local/keytab/daemon.krb5.keytab daemon/machine.mit.edu@ATHENA.MIT.EDU
In the example 2, since kerberosCache is not specified, the default cache, FILE:/tmp/krb5cc_mitidws, will be used. The keytab file is daemon.krb5.keytab and is located in the /usr/local/keytab directory. The kerberos principal of the keytab is daemon/machine.mit.edu@ATHENA.MIT.EDU