Metacat

which is accessed at the following URL::

   http://somehost.somelocation.edu/context/style/skins/dev/replControl.html

Also note that you must SCP partner certificates to your machine; you cannot 

use the "Download Certificate from" option on the Control Panel. For more 

information about creating and installing certificates, please see Generating 

and Exchanging Security Certificates.

The certificates will be exchanged so that each machine understands that the 

other has replication access.

The process for generating certificates is different for Metacat servlets 

running under Tomcat and those under Tomcat/Apache (the recommended configuration). 

For instructions on generating and exchanging certificates on systems running 

only Tomcat (and Java 6), see Generating a Certificate for Tomcat standalone 

(no Apache).

1. Generate a certificate key using openssl. The key will be named 

   came from. 

3. Enter the certificate into Apache's security configuration. You must 

4. Apache needs to know about Metacat SSL. The helper file named "knb-ssl" has 

   rules that tell Apache which traffic to route to the Metacat SSL port. Set up 

   SSL by dropping the knb-ssl file into the sites-available directory and 

   running ``a2ensite`` to enable the site: 

6. SCP ``<hostname>-apache.crt`` to the replication partner machine.

Generating a Certificate for Tomcat standalone (no Apache)

..........................................................

If you are running Metacat under Tomcat (no Apache), generate keys in the Java 

default key store.  The generated key is placed into the binary certificate's 

file located at ``/etc/java-1.5.0-sun/security/cacerts``.

1. Generate the key by running the following command (note that you must be 

   logged in as the root user to use the keytool):

   ::

     keytool -genkey -alias <aliasname> -keyalg RSA -validity 800 -keystore /etc/java-1.6.0-sun/security/cacerts

   ``<aliasname>`` is a unique name that you choose for this key. Something 

   like "<hostname-tomcat>" might be appropriate, where ``<hostname-tomcat>`` 

   is the name of the Metacat host. 

2. The Password-keytool will ask for a password. If writing to a pre-existing 

   keystore, you must know the password. If you are creating a new keystore, 

   the password you enter will become the keystore password. 

   Sample values when creating certificate: 

   ::

     What is your first and last name? myserver.nceas.ucsb.edu (note: use the host name without port number) 

     What is the name of your organizional unit? NCEAS 

     What is the name of your organizional unit? UCSB 

     What is the name of your City or Locality? Santa Barbara 

     What is the name of your State or Province? California (note: this is spelled in full) 

     What is the two-letter country code for this unit? US 

3. Create a certificate by running the command:

   ::

     keytool -export -alias <aliasname> -file <outputfile>.cert -keystore /etc/java-1.6.0-sun/security/cacerts

   ``<aliasname>`` is the same name you used when you created the key file. A 

   file named ``<outputfile>.cert`` will be created in the directory from which 

   you ran the keytool command. You can name the output file anything you like, 

   but keep in mind that it will be sent to the partner machine used for 

   replication. The filename should have enough meaning that someone who sees 

   it on that machine can figure out where it came from. Again, something like 

   "<hostname>-tomcat.cert" will suffice. 

4. Edit the Tomcat server file at ``$TOMCAT_HOME/conf/server.xml`` to enable 

   SSL in Tomcat.

   * Uncomment the section that starts with "<Connector port="8443" ...

     (Note: Databased Information comments start with <!-- and end with -->). 

   * Add two attribute to that section: 

     ::

       keystoreFile="/etc/java-1.6.0-sun/security/cacerts"

       keystorePass="<keystore_password>"

     where ``<keystore_password>`` is the password you used when you created 

     or accessed the keystore. 

5. SCP the certificate to the partner server.

1. Log in as a root user (the keytool must run as a root user)

     sudo su –

2. Import the remote certificate by running: 

     keytool -import -alias <remotehostalias> -file <remotehostfilename>.crt -keystore /etc/java-1.6.0-sun/security/cacerts

   The ``<remotehostalias>`` is the name the certificate will use in the 

   keystore. The name should identify the remote host. 

or use the local machine as a hub). Note that you cannot download certificates 

using this interface.

into effect. To restart Tomcat, log in as the user that runs your Tomcat 

server (often "tomcat") and type: /etc/init.d/tomcat5.5 restart or an 

  The EarthGrid/EcoGrid web service API is *deprecated* and will be removed from

  a future version of Metacat.  Its functionality is being replaced by the 

  standardized DataONE REST service interface.

client API, include the ``metacat-client.jar``, ``utilities.jar``, and 

.. figure:: images/screenshots/image007.jpg

GeoServer 1.4.0, an open source Web Mapping Service (WMS) written in Java, is 

maps (see figure). Metacat uses Community MapBuilder (a pure HTML and JavaScript 

application that uses AJAX and XSLT) to provide a web-based user interface for 

interacting with the generated maps. You can use any WMS-compatible client 

(e.g., ArcGIS, QGIS, JUMP, UDig, OpenLayers, Mapbender, Map Builder). Please 

note the mapping functionality is only supported for Metacat servlets running 

under Tomcat 6 or later. 

Geoserver Password Configuration.

* The GeoServer will only map documents that are publicly available. This is 

* The GeoServer can only access documents that conform to one chosen schema. 

  This is because only one set of xpaths can be defined in the Metacat properties.

* GeoServer 1.4, the version bundled with Metacat, does not support raster 

  input (e.g., satellite imagery or digital elevation models). We suggest 

  setting up UMN Mapserver if you aim to serve raster data. 

the mapping software.

Metacat's GeoServer is automatically installed when Metacat is installed. If 

you do NOT wish to run GeoServer, set the runSpatialOption property in the 

``metacat.properties`` file (found in the source code's lib directory) to 

false before building and deploying Metacat. 

The GeoServer bundled with Metacat comes with a world-countries base layer 

and a default configuration that is already aware of Metacat's spatial cache. 

To further configure GeoServer, use its Web-based configuration utility, 

* Changing the Lat/Long Display to Degree-Minutes-Seconds

.. figure:: images/screenshots/image053.jpg

Community Mabuilder, which Metacat uses as the front-end for GeoServer's WMS 

service, provides interface components or "widgets" (e.g., the map, a box zoom, 

layer list, "Select Location" drop-down menu, scale bar, lat/long coordinates, 

and a query form) that make it easy to deploy highly-functional Web mapping 

applications with minimal coding. The WMS layers are configured through a Web 

Map Context (WMC) document. This context document can be edited to customize 

the initial extent of the map, the ordering and visibility of layers and, of 

course, the source and name of the WMS layer.

Mapbuilder has three main configuration files used to customize the map 

interface (Table 5.1). If you plan to customize the map interface, you must 

use a source code distribution of Metacat. Default configurations are in::

  $METACAT/lib/style/common/spatial_templates/spatial1/

+--------------------------------+-------------+---------------------------------------------------------------------+

| Document                       | Location    | Description                                                         |

+================================+=============+=====================================================================+

| Web map context document (WMC) | context.xml | The WMC is used to customize the initial extent of the map,         |

|                                |             | the order of the map layers, and the source and name of each layer. |

+--------------------------------+-------------+---------------------------------------------------------------------+

| Mapbuilder configuration file  | context.xml | Defines the Mapbuilder widgets and their behavior                   |

+--------------------------------+-------------+---------------------------------------------------------------------+

| The Map file                   | map.html    | Loads the Mapbuilder JavaScript library and controls the            |

|                                |             | HTML layout of the widgets.                                         |

+--------------------------------+-------------+---------------------------------------------------------------------+

  <iframe scrolling="no" frameborder="0" width="736" height="520" 

          src="/knb/style/common/spatial_templates/spatial1/map.html">

The map URL, ``/knb/style/common/spatial_templates/spatial1/map.html``, is 

the default map interface. If you plan to customize the map interface, copy 

the spatial1 directory into your skin's directory (either the default or 

  cp -r style/common/spatial_templates/spatial1 /style/skins/<myskin>/spatial

You can access the customized map with the URL: ``/knb/style/skins/<myskin>/spatial/map.html`` 

have copied the default spatial settings into your skin's directory (see :doc:`configuration`). 

Once the settings have been copied, you can modify the map's initial extent in 

the context settings: ``${skin.dir}/spatial/context.xml``. 

To change the map size and/or initial extent, edit the following lines::

  <Window width="720" height="360" />

  <BoundingBox SRS="EPSG:4326" minx="-180" miny="-90" maxx="180" maxy="90" />

Where ``width`` and ``height`` specify the map size in pixels, ``minx/maxx`` 

represent the range of longitudes and ``miny/maxy`` represent the range of latitudes. 

Before you configure the size and initial extent of the map, make sure that 

you have copied the default spatial settings into your skin's directory. 

Once the settings have been copied, you can modify the layout here: 

``${skin.dir}/spatial/map.html``.

``Map.html`` is a simple HTML file with a tabular layout. Map components are 

abstracted into "widgets", blocks with a specific id (e.g., locationsSelect 

and mainButtonBar), which can be reorganized within the table. 

To customize the map extent and appearance, modify the Web map context 

document (``context.xml``) and/or Mapbuilder's configuration file (``config.xml``). 

Both files are in the spatial directory inside the skins folder.

Changing the Lat/Long Display to Degree-Minutes-Seconds

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the map display shows the cursor's position in decimal degrees 

(the preferred format for many GPS/GIS applications). To report coordinates as 

degrees minutes-seconds, edit the spatial configuration file:

1. If you have not already copied the default spatial settings into your skin's 

   directory, do so now

2. Open the ${skin.dir}/spatial/config.xml file.

3. Edit the CursorTrack widget so that the content is the following: 

::

  <CursorTrack id="cursorTrack">

     <mouseHandler>mainMap</mouseHandler>

     <showDMS>true</showDMS>

     <showLatLong>true</showLatLong>

  </CursorTrack>

4. Save and close the configuration file.

Before you configure the menu items, make sure that you have copied the default 

spatial settings into your skin's directory. 

in the ``${skin.dir}/spatial/named_locations.xml`` file. Each location is 

defined as a ``gml:featureMember``. Edit the featureMember's ``gml:name`` and 

``gml:coordinates`` fields to edit or add new locations. 

  <gml:featureMember>

     <locationDef>

          <gml:name>ACM Wilderness Field Station</gml:name>

          <spatialKeyword>

               <gml:location>

                    <gml:Envelope srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">

                         <gml:coordinates>-91.956,47.87 -91.706,48.12</gml:coordinates>

                    </gml:Envelope>

               </gml:location>

          </spatialKeyword>

     </locationDef>

  </gml:featureMember> 

You can find a more detailed tutorial on using SLD with GeoServer at::

  http://geoserver.org/display/GEOSDOC/SLD+Intro+Tutorial.

1. Point your browser to http://your.server/context/geoserver.jsp, log in to 

   GeoServer, and navigate to the "Data Stores" configuration page 

   under Config > Data > Stores. 

2. Create a new Shapefile and assign it a DataStore ID. The DataStore ID can 

   contain letters and numbers. It is just used internally, and should be 

   unique. Click New.

.. figure:: images/screenshots/image055.jpg

3. On the next screen, select the "metacat" namespace from the drop-down menu 

   and point to the GIS data file on the file system, relative to:

   ::

     {tomcat.dir}/webapps/{context}/

   The Description, if specified, is mostly used internally to provide other 

4. Navigate to the "Feature Type" configuration page under 

   Config > Data > Feature Type. Select your new data store from the 

   drop-down menu. Click New.

5. Style the layer using a style from the drop-down style menu, or click 

   "Create new SLD" to create a new Style object and corresponding SLD 

   (this option provides more control over the style). You should also define a 

   spatial reference system (SRS) number for the new layer. 

   Most lat/long data is "4326". If your data is in another projection,

   determine its spatial reference system using the help links provided. 

.. figure:: images/screenshots/image057.jpg

   GeoServer's FeatureType Editor. The Style and SRS settings discussed in step 5 are highlighted.

6. Click "Apply" and "Save" 

7. Try out the styled data set as a WMS layer using a URL like: 

   ::

     http://your.server/context/wms?VERSION=1.1.1&REQUEST=GetMap&SERVICE=WMS&LAYERS=metacat:newLayer&SRS=EPSG:4326&BBOX=-180,-90,180,90&WIDTH=720&HEIGHT=360&FORMAT=image/gif&STYLES=&TRANSPARENT=TRUE&UNIQUEID= 

   Where your.server/context is the name of your server and context (e.g., 

   http://knb.ecoinformatics.org/knb) and newLayer is the name of the new layer. 

   The other parameters control which part of the layer is displayed.

   If data is properly displayed, add the map to your map context document (Step 8).

8. Locate the Web map context document (usually {skin}/spatial/context.xml) and 

   open the file in a text editor.

9. Locate the Layer entry for an existing layer next to which you wish to stack 

   your layer (the first layers in the context are rendered at the bottom). 

10. Create a new Layer entry, by copying and pasting the existing entry for the 

    metacat data_points layer and editing the Layer Name and Title. The title 

    is displayed in the map legend. Note: if you'd like to use transparency, 

    leave the image format set to image/gif (IE pre-7 has trouble with PNG 

    transparency).

    ::

      <Layer queryable="0" hidden="0">

      <Server service="OGC:WMS" version="1.1.1"

      title="DatasetPoints">

        <OnlineResource xlink:type="simple" xlink:href="../../../../wms" />

      </Server>

      <Name>metacat:data_points</Name>

      <Title>Dataset Points</Title>

      <SRS>EPSG:4326</SRS>

      <FormatList>

        <Format current="1">image/gif</Format>

      </FormatList>

      </Layer>

11. Point your browser to the map interface. Your new layer should appear with 

through WMS. (check out http://wms-sites.com for good catalog). To add these 

data sources to your map, locate your skin's context file 

(``${skin.dir}/spatial/context.xml``) and add a new Layer by copying and 

pasting an existing Layer and modifying as appropriate: modify the 

OnlineResourceURL, Name, Title and Style to match the WMS layer you'd like to 

use. See the mapbuilder Add WMS Tutorial for further details.

* Java_ 6 (Note: Java 5 is deprecated)

.. _Java: http://www.oracle.com/technetwork/java/javaee/overview/index.html

1. Download and install prerequisites (Java_ 6, `Apache Tomcat`_ 6, PostgreSQL_, `Apache HTTPD Server`_), including the tomcat6 init.d script

7. ``sudo /etc/init.d/tomcat5.5 restart``

Knb.ssl            The SSL definition file used by Apache on Ubuntu/Debian 

tomcat5.5          The Tomcat startup script for Tomcat 5.5 installed with 

                   apt-get on Ubuntu/Debian Linux systems.

* Java_ 6

  sudo apt-get install tomcat5.5

Install the Metacat-friendly Tomcat start-up script by typing::

  sudo /etc/init.d/tomcat5.5 stop

  sudo mv /etc/init.d/tomcat5.5 /etc/init.d/tomcat5.5.bak

  sudo cp <metacat_package_dir>/debian/tomcat5.5 /etc/init.d/tomcat5.5

  sudo chmod +x /etc/init.d/tomcat5.5

PostgreSQL Database 

with Ant 1.6.5. 

3)  Install the Metacat WAR in the Tomcat web-application directory. For instructions on downloading the Metacat WAR, please see Downloading Metacat.  Typically, Tomcat will look for its application files (WAR files) in the <tomcat_home>/webapps directory (e.g., /usr/share/tomcat5.5/webapps). Your instance of Tomcat may be configured to look in a different directory. We will refer to the Tomcat application directory as <tomcat_app_dir>.  NOTE: The name of the WAR file (e.g., knb.war) provides the application context, which appears in the URL of the Metacat (e.g., http://yourserver.com/knb/). To change the context, simply change the name of the WAR file to the desired name before copying it.  To install the Metacat WAR:

    /etc/init.d/tomcat5.5 restart

.. figure:: images/screenshots/image009.jpg

    /etc/init.d/tomcat5.5 stop

    /etc/init.d/tomcat5.5 restart

    sudo cp <metacat_package_directory>/authority.war /usr/share/tomcat5.5/webapps

    /etc/init.d/tomcat5.5 restart

   version of Metacat (e.g., 1.9.0).

* Java_ 6

1. Browse to: http://tomcat.apache.org/download-55.cgi 

.. sidebar:: Version: 2.0.0 Release

.. figure:: images/screenshots/image013.png

.. figure:: images/screenshots/image015.jpg

Geoserver Password Configuration (Highly Recommended)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  1. Go to the Geoserver admin page: http://<your_context_url>/geoserver.jsp. 

  Note that once you change the Geoserver credentials manually, you cannot use 

  the Metacat configuration tool to change it again (until a new Metacat 

  upgrade or installation).

a default administrative username and password. We highly recommend that you 

change the default log-in information so that only local administrators can make 

changes to your Geoserver. For more information about Geoserver, 

screen, Metacat will prompt you for a new user name and password. After you 

enter the new credentials, the Metacat server contacts the embedded Geoserver s

erver and updates the log-in settings.

If you wish to reset the Geoserver credentials at another time, click the 

Bypass button. The Geoserver will remain configured with the default user name 

and password, and the main configuration screen will display the "bypassed" 

status beside the Geoserver settings. You will be able to run Metacat, just as 

if the settings were configured.

   Resetting the Geoserver password.

lives (e.g., ``/usr/share/tomcat5.5/webapps/knb``). The path is a combination 

of the Web application directory (e.g., ``/usr/share/tomcat5.5/webapps/``) and 

    /etc/init.d/tomcat5.5 restart