Using virtual services

Virtual services provide a way to section off GeoServer layers. Using virtual services, a user can interact with GeoServer through standard OGC protocols while only a subset of the published layers is visible. This is advantageous for when there are multiple project administrators working on the same GeoServer instance, or when a given GeoServer instance is serving a large amount of layers, making the capabilities documents time-consuming to load.

Virtual services operate by providing workspace-specific endpoints for OGC services. Using these endpoints, the user/client will only “see” the layers associated with that particular workspace.

From an administration perspective, virtual services allows the roles of GeoServer administrator and project administrator to be separated.

This tutorial will show how to implement a typical scenario utilizing virtual services.

Note

Read more about Virtual Services in the GeoServer reference.

Scenario

There are two project administrators working on the same GeoServer instance. One is working on the Lakes project. She wants to be able to load and administer all of the data related to her project, but does not need to know about or administer any other project. The other project administrator is working on the Traffic project. He too wants to be able to load and administer all of the data related to his project, but does not need to know about or administer any other project.

To configure this scenario, the following steps must be taken:

  • Create two workspaces: lakes and traffic
  • Load all relevant data to the proper workspace
  • Instruct usage of virtual services endpoints
  • Disable global service endpoints

Creating workspaces

First, configure the virtual service endpoints.

  1. From the GeoServer web interface, log in to the administrator account.

  2. Click Workspaces.

    ../../_images/workspaceslink.png

    Click to manage workspaces

  3. Click Add new workspace.

    ../../_images/addnewworkspacelink.png

    Click to add a new workspace

  4. Fill out the form:

    • In the box titled Name, enter lakes
    • In the box titled Namespace URI, enter http://lakes.
    • Do not check the Default Workspace box.

    Click Submit when done.

    ../../_images/workspacelakes.png

    New workspace: Lakes

  5. Click on Add new workspace again.

  6. Fill out the form:

    • In the box titled Name, enter traffic
    • In the box titled Namespace URI, enter http://traffic.
    • Do not check the Default Workspace box.

    Click Submit when done.

    ../../_images/workspacetraffic.png

    New workspace: Traffic

    Note

    Workspace creation can also be done programmatically through the REST API by submitting a POST request to this endpoint:

    http://<GEOSERVER_URL>/rest/workspaces

    with the following content:

    <workspace><name>lakes</name></workspace>

  7. To verify that the virtual service endpoints have been configured correctly, navigate to the following URLs:

    http://<GEOSERVER_URL>/lakes/wfs?request=GetCapabilities
http://<GEOSERVER_URL>/traffic/wfs?request=GetCapabilities
    ../../_images/validcaps.png

    A valid capabilities document from a virtual service

    If a valid capabilities document displays, the workspaces were set up correctly. If a 404 error page displays, the workspace may not have been created successfully. If so, please retry the above steps.

  8. Similar verification can be done with the equivalent WMS virtual service endpoints:

    http://<GEOSERVER_URL>/lakes/wms?request=GetCapabilities
http://<GEOSERVER_URL>/traffic/wms?request=GetCapabilities

Setting virtual service metadata

It is possible to have separate metadata for each virtual service. To change the metadata for each virtual service:

  1. From the main GeoServer menu, click Workspaces.

  2. Click the lakes workspace.

  3. Under the Settings section, click the Enabled checkbox. This will enable workspace-level metadata, and create a copy of the global service metadata.

    ../../_images/enablemetadata.png

    Enabling workspace-specific metadata

  4. Make any changes to the metadata as desired. Click Save when finished.

    ../../_images/editingmetadata.png

    Editing workspace-specific metadata

  5. Verify that the changes have been applied by executing a GetCapabilities request to the virtual service endpoint as above:

    http://<GEOSERVER_URL>/lakes/wms?request=GetCapabilities
    ../../_images/editedmetadatacapabilities.png

    Capabilities document with virtual service-specific metadata

  6. Repeat this process for the traffic workspace.

Loading layers

The process for loading layers remains unchanged. See the section on Working with your data for more information. Make sure that all layers and stores are in the appropriate workspace.

Note

If layers had been already loaded prior to the creation of these workspaces, the layers will need to be migrated to the appropriate workspace. To migrate layers from one workspace to another, move the stores that the layers are contained in, and all the contained layers will switch workspaces.

Loading styles

Note

Because styles are visible in all virtual service endpoints by default, this step is optional.

Styles for layers are not workspace-specific by default. To set a style to be visible only for a given workspace:

  1. From the main GeoServer menu, click Styles.

  2. Click on the name of the style to edit.

  3. Under the Workspace heading, select the appropriate workspace.

    ../../_images/styleworkspace.png

    Setting a workspace-specific style

Verifying virtual services

Now that all layers are in their appropriate workspaces, verify this by navigating to any of the virtual service endpoints mentioned above:

http://<GEOSERVER_URL>/lakes/wms?request=GetCapabilities
http://<GEOSERVER_URL>/traffic/wms?request=GetCapabilities

Scroll down in the document to the <Layer> section (<FeatureTypeList> for WFS). The layers loaded in that workspace should be listed but should also be the only layers listed.

You can also verify virtual services in GeoExplorer.

  1. Open GeoExplorer.

  2. Open the Add Layers dialog.

    ../../_images/geoexplorer_addlayerslink.png

    Adding layers in GeoExplorer

  3. In the select box titled View available data from:, select Add a New Server....

    ../../_images/geoexplorer_addnewserverlink.png

    Adding a new WMS server in GeoExplorer

  4. In the URL field, enter one of the WMS virtual service endpoints.

    ../../_images/geoexplorer_addnewserverdialog.png

    Entering the virtual service endpoint

  5. Click Add Server.

  6. The layers listed should be only those loaded into that particular workspace.

    ../../_images/geoexplorer_vslayers.png

    Virtual service layers

Restricting global services

A key benefit of virtual services is segmentation; no user needs to see every single layer in GeoServer. Because of this, once workspaces are properly set up, global services can be disabled.

  1. Click Global under Settings.

    ../../_images/globalsettingslink.png

    Click to manage GeoServer global settings

  2. Uncheck Enable Global Services.

    ../../_images/globalservicesdisabled.png

    Global service disabled

  3. Click Submit.

    Note

    Disabling global services can also be done programmatically through the REST API by submitting a PUT request to this endpoint:

    http://<GEOSERVER_URL>/rest/settings/

    with the following content:

    <global><globalServices>false</globalServices></global>

  4. Verify that the global endpoint has been disabled by navigating to the following URL:

    http://<GEOSERVER_URL>/wfs?request=GetCapabilities

    The response should include the following error message: “No workspace specified“

    ../../_images/noworkspacespecified.png

    Exception when viewing a disabled global capabilities document

  5. The virtual service endpoints will still be valid:

    http://<GEOSERVER_URL>/lakes/wfs?request=GetCapabilities
http://<GEOSERVER_URL>/traffic/wfs?request=GetCapabilities