1. About DDF
1.1. Introducing DDF
Distributed Data Framework (DDF) is a free and open-source common data layer that abstracts services and business logic from underlying data structures to enable rapid integration of new data sources.
Licensed under LGPL , DDF is an interoperability platform that provides secure and scalable discovery and retrieval from a wide array of disparate sources.
DDF is:
-
a flexible and modular integration framework.
-
built to "unzip and run" even when scaled to large enterprise systems.
-
primarily focused on data integration, enabling clients to insert, query, and transform information from disparate data sources via the DDF Catalog.
1.2. Component Applications
DDF is comprised of several modular applications, to be installed or uninstalled as needed.
- Admin Application
-
Enhances administrative capabilities when installing and managing DDF. It contains various services and interfaces that allow administrators more control over their systems.
- Catalog Application
-
Provides a framework for storing, searching, processing, and transforming information. Clients typically perform local and/or federated query, create, read, update, and delete (QCRUD) operations against the Catalog. At the core of the Catalog functionality is the Catalog Framework, which routes all requests and responses through the system, invoking additional processing per the system configuration.
- Platform Application
-
The Core application of the distribution. The Platform application contains the fundamental building blocks to run the distribution.
- Security Application
-
Provides authentication, authorization, and auditing services for the DDF. It is both a framework that developers and integrators can extend and a reference implementation that meets security requirements.
- Solr Catalog Application
-
Includes the Solr Catalog Provider, an implementation of the Catalog Provider using Apache Solr as a data store.
- Spatial Application
- Search UI
-
Allows a user to search for records in the local Catalog (provider) and federated sources. Results of the search are returned and displayed on a globe or map, providing a visual representation of where the records were found.
2. Documentation Guide
The DDF documentation is organized by audience.
- Core Concepts
-
This introduction section is intended to give a high-level overview of the concepts and capabilities of DDF.
- Administrators
-
Managing | Administrators will be installing, maintaining, and supporting existing applications. Use this section to prepare, install, configure, run, and monitor DDF.
- Users
-
Using | Users interact with the system to search data stores. Use this section to navigate the various user interfaces available in DDF.
- Integrators
-
Integrating | Integrators will use the existing applications to support their external frameworks. This section will provide details for finding, accessing and using the components of DDF.
- Developers
-
Developing | Developers will build or extend the functionality of the applications.
2.1. Documentation Conventions
The following conventions are used within this documentation:
2.1.1. Customizable Values
Many values used in descriptions are customizable and should be changed for specific use cases.
These values are denoted by < >
, and by [[ ]]
when within XML syntax. When using a real value, the placeholder characters should be omitted.
2.1.2. Code Values
Java objects, lines of code, or file properties are denoted with the Monospace
font style.
Example: ddf.catalog.CatalogFramework
2.1.3. Hyperlinks
Some hyperlinks (e.g., /admin
) within the documentation assume a locally running installation of DDF.
Simply change the hostname if accessing a remote host.
Hyperlinks that take the user away from the DDF documentation are marked with an external link
() icon.
2.2. Support
Questions about DDF should be posted to the ddf-users forum or ddf-developers forum , where they will be responded to quickly by a member of the DDF team.
2.2.1. Documentation Updates
The most current DDF documentation is available at DDF Documentation .
3. Core Concepts
This introduction section is intended to give a high-level overview of the concepts and capabilities of DDF.
3.1. Introduction to Search
DDF provides the capability to search the Catalog for metadata. There are a number of different types of searches that can be performed on the Catalog, and these searches are accessed using one of several interfaces. This section provides a very high-level overview of introductory concepts of searching with DDF. These concepts are expanded upon in later sections.
There are four basic types of metadata search. Additionally, any of the types can be combined to create a compound search.
- Text Search
-
A text search is used when searching for textual information. It searches all textual fields by default, although it is possible to refine searches to a text search on a single metadata attribute. Text searches may use wildcards, logical operators, and approximate matches.
- Spatial Search
-
A spatial search is used for Area of Interest (AOI) searches. Polygon and point radius searches are supported.
- Temporal Search
-
A temporal search finds information from a specific time range. Two types of temporal searches are supported: relative and absolute. Relative searches contain an offset from the current time, while absolute searches contain a start and an end timestamp. Temporal searches can use the
created
ormodified
date attributes. - Datatype Search
-
A datatype search is used to search for metadata based on the datatype of the resource. Wildcards (*) can be used in both the datatype and version fields. Metadata that matches any of the datatypes (and associated versions if specified) will be returned. If a version is not specified, then all metadata records for the specified datatype(s) regardless of version will be returned.
3.2. Introduction to Metadata
In DDF, resources are the data products, files, reports, or documents of interest to users of the system.
Metadata is information about those resources, organized into a schema to make search possible. The Catalog stores this metadata and allows access to it. Metacards are single instances of metadata, representing a single resource, in the Catalog. Metacards follow one of several schemas to ensure reliable, accurate, and complete metadata. Essentially, Metacards function as containers of metadata.
3.3. Introduction to Ingest
Ingest is the process of bringing data products, metadata, or both into the catalog to enable search, sharing, and discovery. Ingested files are transformed into a neutral format that can be searched against as well as migrated to other formats and systems. See Ingesting Data for the various methods of ingesting data.
Upon ingest, a transformer will read the metadata from the ingested file and populate the fields of a metacard. Exactly how this is accomplished depends on the origin of the data, but most fields (except id) are imported directly.
3.4. Introduction to Resources
The Catalog Framework can interface with storage providers to provide storage of resources to specific types of storage, e.g., file system, relational database, XML database. A default file system implementation is provided by default.
Storage providers act as a proxy between the Catalog Framework and the mechanism storing the content. Storage providers expose the storage mechanism to the Catalog Framework. Storage plugins provide pluggable functionality that can be executed either immediately before or immediately after content has been stored or updated.
Storage providers provide the capability to the Catalog Framework to create, read, update, and delete resources in the content repository.
See Data Management for more information on specific file types supported by DDF.
3.5. Introduction to the Catalog Framework
The Catalog Framework wires all the Catalog components together.
It is responsible for routing Catalog requests and responses to the appropriate source, destination, federated system, etc.
Endpoints send Catalog requests to the Catalog Framework. The Catalog Framework then invokes Catalog Plugins, Transformers, and Resource Components as needed before sending requests to the intended destination, such as one or more Sources.
The Catalog Framework decouples clients from service implementations and provides integration points for Catalog Plugins and convenience methods for Endpoint developers.
3.6. Introduction to Federation and Sources
Federation is the ability of the DDF to query other data sources, including other DDFs. By default, the DDF is able to federate using OpenSearch and CSW protocols. The minimum configuration necessary to configure those federations is a query address.
Federation enables constructing dynamic networks of data sources that can be queried individually or aggregated into specific configuration to enable a wider range of accessibility for data and data products.
Federation provides the capability to extend the DDF enterprise to include Remote Sources, which may include other instances of DDF. The Catalog handles all aspects of federated queries as they are sent to the Catalog Provider and Remote Sources, as they are processed, and as the query results are returned. Queries can be scoped to include only the local Catalog Provider (and any Connected Sources), only specific Federated Sources, or the entire enterprise (which includes all local and Remote Sources). If the query is federated, the Catalog Framework passes the query to a Federation Strategy, which is responsible for querying each federated source that is specified. The Catalog Framework is also responsible for receiving the query results from each federated source and returning them to the client in the order specified by the particular federation strategy used. After the federation strategy handles the results, the Catalog returns them to the client through the Endpoint. Query results are returned from a federated query as a list of metacards. The source ID in each metacard identifies the Source from which the metacard originated.
3.7. Introduction to Events and Subscriptions
DDF can be configured to receive notifications whenever metadata is created, updated, or deleted in any federated sources. Creations, updates, and deletions are collectively called Events, and the process of registering to receive them is called Subscription.
The behavior of these subscriptions is consistent, but the method of configuring them is specific to the Endpoint used.
3.8. Introduction to Registries
The Registry Application serves as an index of registry nodes and their information, including service bindings, configurations and supplemental details.
Each registry has the capability to serve as an index of information about a network of registries which, in turn, can be used to connect across a network of DDFs and other data sources. Registries communicate with each other through the CSW endpoint and each registry node is converted into a registry metacard to be stored in the catalog. When a registry is subscribed to or published from, it sends the details of one or more nodes to another registry.
- Identity Node
-
The Registry is initially comprised of a single registry node, refered to as the identity, which represents the registry’s primary configuration.
- Subscription
-
Subscribing to a registry is the act of retreiving its information, specifically its identity information and any other registries it knows about. By default, subscriptions are configured to check for updates every 30 seconds.
- Publication
-
Publishing is the act of sending a registry’s information to another registry. Once publication has occurred, any updates to the local registry will be pushed out to the registries that have been published to.
3.9. Introduction to Endpoints
Endpoints expose the Catalog Framework to clients using protocols and formats that the clients understand.
Endpoint interface formats encompass a variety of protocols, including (but not limited to):
-
SOAP Web services
-
RESTful services
-
JMS
-
JSON
-
OpenSearch
The endpoint may transform a client request into a compatible Catalog format and then transform the response into a compatible client format. Endpoints may use Transformers to perform these transformations. This allows an endpoint to interact with Source(s) that have different interfaces. For example, an OpenSearch Endpoint can send a query to the Catalog Framework, which could then query a federated source that has no OpenSearch interface.
Endpoints are meant to be the only client-accessible components in the Catalog.
3.10. Introduction to High Availability
DDF can be made highly available. In this context, High Availability is defined as the ability for DDF to be continuously operational with very little down time.
In a Highly Available Cluster, DDF has failover capabilities when a DDF node fails.
Note
|
The word "node", from a High Availability perspective, is one of the two DDF systems running within the Highly Available Cluster. Though there are multiple systems running with the Highly Available Cluster, it is still considered a single DDF from a user’s perspective or from other DDFs' perspectives. |
This setup consists of a Solr Cloud instance, 2 DDF nodes connected to that Solr Cloud, and a failover proxy that sits in front of those 2 nodes. One of the DDF nodes will be arbitrarily chosen to be the active node, and the other will be the "hot standby" node. It is called a "hot standby" node because it is ready to receive traffic even though it’s not currently receiving any. The failover proxy will route all traffic to the active node. If the active node fails for any reason, the standby node will become active and the failover proxy will route all traffic to the new active node. See the below diagrams for more detail.
There are special procedures for initial setup and configuration of a highly available DDF. See High Availability Initial Setup and High Availability Configuration for those procedures.
3.10.1. High Availability Supported Capabilities
Only these capabilities are supported in a Highly Available Cluster.
For a detailed list of features, look at the ha.json
file located in <DDF_HOME>/etc/profiles/
.
-
User Interfaces:
-
Simple
-
Intrigue
-
-
Catalog:
-
Validation
-
Plug-ins: Expiration Date, JPEG2000, Metacard Validation, Schematron, Versioning
-
Transformers
-
Content File System Storage Provider
-
-
Platform:
-
Actions
-
Configuration
-
Notifications
-
Persistence
-
Security: Audit, Encryption
-
-
Solr
-
Security
-
Thirdy Party:
-
CXF
-
Camel
-
-
Endpoints:
-
REST Endpoint
-
CSW Endpoint
-
OpenSearch Endpoint
-
3.11. Standards Supported by DDF
DDF incorporates support for many common Service, Metadata, and Security standards, as well as many common Data Formats.
3.11.1. Catalog Service Standards
Service standards are implemented within Endpoints and/or Sources. Standards marked Experimental are functional and have been tested, but are subject to change or removal during the incubation period.
Standard (public standards linked where available) | Endpoints | Sources | Status |
---|---|---|---|
Open Geospatial Consortium Catalog Service for the Web (OGC CSW) 2.0.1/2.0.2 |
Geographic MetaData extensible markup language (GMD) CSW Source |
Supported |
|
Supported |
|||
OGC WPS 2.0 Web Processing Service |
Experimental |
||
Supported |
|||
Supported |
|||
Atlassian Confluence® |
Supported |
3.11.2. Data Formats
DDF has extended capabilities to extract rich metadata from many common data formats if those attributes are populated in the source document. See appendix for a complete list of file formats that can be ingested with limited metadata coverage. Metadata standards use XML or JSON, or both.
Format | File Extensions | Additional Metadata Attributes Available (if populated) |
---|---|---|
Word Document |
|
|
PowerPoint |
|
|
Excel |
|
|
|
||
GeoPDF |
|
|
geojson |
|
|
html |
|
|
jpeg |
|
Standard attributes and additional Media attributes |
mp2 |
|
Standard attributes and additional Media attributes |
mp4 |
|
Standard attributes, additional Media attributes, and mp4 additional attribute |
WMV |
|
|
AVIs |
|
|
|
||
|
3.11.3. Map Formats
Intrigue includes capabilities to support custom map layer providers as well as support for several popular map layer providers.
Some provider types are currently only supported by the 2D OpenLayers map and some only by the 3D Cesium map.
Format | 2D Documentation | 3D Documentation |
---|---|---|
Open Street Map |
||
Web Map Service |
||
Web Map Tile Service |
||
ArcGIS Map Server |
||
Single Tile |
||
Bing Maps |
||
Tile Map Service |
||
Google Earth |
3.11.4. Security Standards
DDF makes use of these security standards to protect the system and interactions with it.
Standard | Support Status |
---|---|
Supported |
|
Supported |
Standard | Support Status |
---|---|
Supported |
|
|
Supported |
Standard | Support Status |
---|---|
HyperText Transport Protocol (HTTP) / HyperText Transport Protocol Secure (HTTPS) |
Supported |
File Transfer Protocol (FTP) / File Transfer Protocol Secure (FTPS) |
Supported |
Supported |
Standard | Support Status |
---|---|
Supported |
|
Supported |
|
Supported |
Standard | Support Status |
---|---|
Supported |
|
Supported |
|
Supported |
Standard | Support Status |
---|---|
Supported |
|
Supported |
|
Supported |
|
Supported |
4. Quick Start Tutorial
This quick tutorial will enable install, configuring and using a basic instance of DDF.
Note
|
This tutorial is intended for setting up a test, demonstration, or trial installation of DDF. For complete installation and configuration steps, see Installing. |
These steps will demonstrate:
4.1. Installing (Quick Start)
These are the basic requirements to set up the environment to run a DDF.
Warning
|
For security reasons, DDF cannot be started from a user’s home directory. If attempted, the system will automatically shut down. |
4.1.1. Quick Install Prerequisites
-
At least 4096MB of memory for DDF.
-
This amount can be increased to support memory-intensive applications. See Memory Considerations.
-
Follow the instructions outlined here: Java Requirements.
Warning
|
Check System Time
Prior to installing DDF, ensure the system time is accurate to prevent federation issues. |
4.1.2. Quick Install of DDF
-
Download the DDF zip file .
-
Install DDF by unzipping the zip file.
WarningWindows Zip Utility WarningThe Windows Zip implementation, which is invoked when a user double-clicks on a zip file in the Windows Explorer, creates a corrupted installation. This is a consequence of its inability to process long file paths. Instead, use the java jar command line utility to unzip the distribution (see example below) or use a third party utility such as 7-Zip.
Note: If and only if a JDK is installed, the jar command may be used; otherwise, another archiving utility that does not have issue with long paths should be installed
Use Java to Unzip in Windows(Replace<PATH_TO_JAVA>
with correct pathand <JAVA_VERSION>
with current version.)"<PATH_TO_JAVA>\jdk<JAVA_VERSION>\bin\jar.exe" xf ddf-2.21.6.zip
-
This will create an installation directory, which is typically created with the name and version of the application. This installation directory will be referred to as
<DDF_HOME>
. (Substitute the actual directory name.) -
Start DDF by running the
<DDF_HOME>/bin/ddf
script (orddf.bat
on Windows). -
Startup may take a few minutes.
-
Optionally, a
system:wait-for-ready
command (aliased towfr
) can be used to wait for startup to complete.
-
-
The Command Console will display.
ddf@local>
4.1.3. Quick Install of DDF on a remote headless server
If DDF is being installed on a remote server that has no user interface, the hostname will need to be updated in the configuration files and certificates.
Note
|
Do not replace all instances of |
-
Update the <DDF_HOME>/etc/custom.system.properties file. The entry
org.codice.ddf.system.hostname=localhost
should be updated toorg.codice.ddf.system.hostname=<HOSTNAME>
. -
Update the <DDF_HOME>/etc/users.properties file. Change the
localhost=localhost[…]
entry to <HOSTNAME>=<HOSTNAME>. (Keep the rest of the line as is.) -
Update the <DDF_HOME>/etc/users.attributes file. Change the "localhost" entry to "<HOSTNAME>".
-
From the console go to <DDF_HOME>/etc/certs and run the appropriate script.
-
*NIX:
sh CertNew.sh -cn <hostname> -san "DNS:<hostname>"
. -
Windows:
CertNew -cn <hostname> -san "DNS:<hostname>"
.
-
-
Proceed with starting the system and continue as usual.
-
Update the <DDF_HOME>/etc/custom.system.properties file. The entry
org.codice.ddf.system.hostname=localhost
should be updated toorg.codice.ddf.system.hostname=<IP>
. -
Update the <DDF_HOME>/etc/users.properties file. Change the
localhost=localhost[…]
entry to <IP>=<IP>. (Keep the rest of the line as is.) -
Update the <DDF_HOME>/etc/users.attributes file. Change the "localhost" entry to "<IP>".
-
From the console go to <DDF_HOME>/etc/certs and run the appropriate script.
-
*NIX:
sh CertNew.sh -cn <IP> -san "IP:<IP>"
. -
Windows:
CertNew -cn <IP> -san "IP:<IP>"
.
-
-
Proceed with starting the system and continue as usual.
Note
|
File Descriptor Limit on Linux
fs.file-max = 6815744
init 6 |
4.2. Certificates (Quick Start)
DDF comes with a default keystore that contains certificates. This allows the distribution to be unzipped and run immediately. If these certificates are sufficient for testing purposes, proceed to Configuring (Quick Start).
To test federation using 2-way TLS, the default keystore certificates will need to be replaced, using either the included Demo Certificate Authority or by Creating Self-signed Certificates.
If the installer was used to install the DDF and a hostname other than "localhost" was given, the user will be prompted to upload new trust/key stores.
If the hostname is localhost
or, if the hostname was changed after installation, the default certificates will not allow access to the DDF instance from another machine over HTTPS (now the default for many services).
The Demo Certificate Authority will need to be replaced with certificates that use the fully-qualified hostname of the server running the DDF instance.
4.2.1. Demo Certificate Authority (CA)
DDF comes with a populated truststore containing entries for many public certificate authorities, such as Go Daddy and Verisign. It also includes an entry for the DDF Demo Root CA. This entry is a self-signed certificate used for testing. It enables DDF to run immediately after unzipping the distribution. The keys and certificates for the DDF Demo Root CA are included as part of the DDF distribution. This entry must be removed from the truststore before DDF can operate securely.
4.2.1.1. Creating New Server Keystore Entry with the CertNew Scripts
To create a private key and certificate signed by the Demo Certificate Authority, use the provided scripts.
To use the scripts, run them out of the <DDF_HOME>/etc/certs
directory.
The CertNew
scripts:
-
Create a new entry in the server keystore.
-
Use the hostname as the fully qualified domain name (FQDN) when creating the certificate.
-
Adds the specified subject alternative names if any.
-
Use the Demo Certificate Authority to sign the certificate so that it will be trusted by the default configuration.
To install a certificate signed by a different Certificate Authority, see Managing Keystores.
After this proceed to Updating Settings After Changing Certificates.
Warning
|
If the server’s fully qualified domain name is not recognized, the name may need to be added to the network’s DNS server. |
4.2.1.2. Dealing with Lack of DNS
In some cases DNS may not be available and the system will need to be configured to work with IP addresses.
Options can be given to the CertNew Scripts to generate certs that will work in this scenario.
After this proceed to Updating Settings After Changing Certificates, and be sure to use the IP address instead of the FQDN.
4.2.2. Creating Self-Signed Certificates
If using the Demo CA is not desired, DDF supports creating self-signed certificates with a self-signed certificate authority. This is considered an advanced configuration.
Creating self-signed certificates involves creating and configuring the files that contain the certificates.
In DDF, these files are generally Java Keystores (jks
) and Certificate Revocation Lists (crl
).
This includes commands and tools that can be used to perform these operations.
For this example, the following tools are used:
4.2.2.1. Creating a custom CA Key and Certificate
The following steps demonstrate creating a root CA to sign certificates.
-
Create a key pair.
$> openssl genrsa -aes128 -out root-ca.key 1024
-
Use the key to sign the CA certificate.
$> openssl req -new -x509 -days 3650 -key root-ca.key -out root-ca.crt
4.2.2.2. Sign Certificates Using the custom CA
The following steps demonstrate signing a certificate for the tokenissuer
user by a CA.
-
Generate a private key and a Certificate Signing Request (CSR).
$> openssl req -newkey rsa:1024 -keyout tokenissuer.key -out tokenissuer.req
-
Sign the certificate by the CA.
$> openssl ca -out tokenissuer.crt -infiles tokenissuer.req
These certificates will be used during system configuration to replace the default certificates.
4.2.3. Updating Settings After Changing Certificates
After changing the certificates it will be necessary to update the system user and the org.codice.ddf.system.hostname
property with the value of either the FQDN or the IP.
FQDNs should be used wherever possible. In the absence of DNS, however, IP addresses can be used.
Replace localhost
with the FQDN or the IP in <DDF_HOME>/etc/users.properties
, <DDF_HOME>/etc/users.attributes
, and <DDF_HOME>/etc/custom.system.properties
.
Tip
|
On linux this can be accomplished with a single command:
|
Finally, restart the DDF instance. Navigate to the Admin Console to test changes.
4.3. Configuring (Quick Start)
Set the configurations needed to run DDF.
-
In a browser, navigate to the Admin Console at https://{FQDN}:{PORT}/admin.
-
The Admin Console may take a few minutes to start up.
-
-
Enter the default username of
admin
and the password ofadmin
. -
Follow the installer prompts for a standard installation.
-
Click start to begin the setup process.
-
Configure guest claims attributes or use defaults.
-
See Configuring Guest Access for more information about the Guest user.
-
All users will be automatically granted these permissions.
-
Guest users will not be able to ingest data with more restrictive markings than the guest claims.
-
Any data ingested that has more restrictive markings than these guest claims will not be visible to Guest users.
-
-
Select Standard Installation.
-
This step may take several minutes to complete.
-
-
On the System Configuration page, configure any port or protocol changes desired and add any keystores/truststores needed.
-
See Certificates (Quick Start) for more details.
-
-
Click Next
-
Click Finish
-
4.4. Ingesting (Quick Start)
Now that DDF has been configured, ingest some sample data to demonstrate search capabilities.
This is one way to ingest into the catalog, for a complete list of the different methods, see Ingesting Data.
4.4.1. Ingesting Sample Data
-
Download a sample valid GeoJson file here .
-
Navigate in the browser to Intrigue at https://{FQDN}:{PORT}/search/catalog.
-
Select the Menu icon () in the upper left corner
-
Select Upload.
-
Drag and drop the sample file or click to navigate to it.
-
Select Start to begin upload.
Note
|
XML metadata for text searching is not automatically generated from GeoJson fields. |
Querying from Intrigue (https://{FQDN}:{PORT}/search/catalog) will return the record for the file ingested:
-
Select the Menu icon ()and return to Workspaces.
-
Search for the ingested data.
Note
|
The sample data was selected as an example of well-formed metadata. Other data can and should be used to test other usage scenarios. |
Managing
Administrators will be installing, maintaining, and supporting existing applications. Use this section to prepare, install, configure, run, and monitor a DDF.
5. Securing
Security is an important consideration for DDF, so it is imperative to update configurations away from the defaults to unique, secure settings.
Important
|
Securing DDF Components
DDF is enabled with an Insecure Defaults Service which will warn users/admins if the system is configured with insecure defaults. A banner is displayed on the admin console notifying "The system is insecure because default configuration values are in use." A detailed view is available of the properties to update. |
Security concerns will be highlighted in the configuration sections to follow.
5.1. Security Hardening
Note
|
The security precautions are best performed as configuration is taking place, so hardening steps are integrated into configuration steps. |
This is to avoid setting an insecure configuration and having to revisit during hardening. Most configurations have a security component to them, and important considerations for hardening are labeled as such during configuration as well as provided in a checklist format.
Some of the items on the checklist are performed during installation and others during configuration. Steps required for hardening are marked as Required for Hardening and are collected here for convenience. Refer to the checklist during system setup.
5.2. Auditing
-
Required Step for Security Hardening
Audit logging captures security-specific system events for monitoring and review.
DDF provides an Audit Plugin that logs all catalog transactions to the security.log
.
Information captured includes user identity, query information, and resources retrieved.
Follow all operational requirements for the retention of the log files. This may include using cryptographic mechanisms, such as encrypted file volumes or databases, to protect the integrity of audit information.
Note
|
The Audit Log default location is |
Note
|
Audit Logging Best Practices
For the most reliable audit trail, it is recommended to configure the operational environment of the DDF to generate alerts to notify adminstrators of:
|
Warning
|
The security audit logging function does not have any configuration for audit reduction or report generation. The logs themselves could be used to generate such reports outside the scope of DDF. |
5.2.1. Enabling Fallback Audit Logging
-
Required Step for Security Hardening
In the event the system is unable to write to the security.log
file, DDF must be configured to fall back to report the error in the application log:
-
edit
<DDF_HOME>/etc/org.ops4j.pax.logging.cfg
-
uncomment the line (remove the
#
from the beginning of the line) forlog4j2
(org.ops4j.pax.logging.log4j2.config.file = ${karaf.etc}/log4j2.xml
) -
delete all subsequent lines
-
If you want to change the location of your systems security backup log from the default location: <DDF_HOME>/data/log/securityBackup.log
, follow the next two steps:
-
edit
<DDF_HOME>/security/configurations.policy
-
find "Security-Hardening: Backup Log File Permissions"
-
below
grant codeBase "file:/pax-logging-log4j2"
add the path to the directory containing the new log file you will create in the next step.
-
-
edit
<DDF_HOME>/etc/log4j2.xml
-
find the entry for the
securityBackup
appender. (see example) -
change value of
filename
and prefix offilePattern
to the name/path of the desired failover security logs
-
securityBackup
Appender Before
1
2
3
<RollingFile name="securityBackup" append="true" ignoreExceptions="false"
fileName="${sys:karaf.log}/securityBackup.log"
filePattern="${sys:karaf.log}/securityBackup.log-%d{yyyy-MM-dd-HH}-%i.log.gz">
securityBackup
Appender After
1
2
3
<RollingFile name="securityBackup" append="true" ignoreExceptions="false"
fileName="<NEW_LOG_FILE>"
filePattern="<NEW_LOG_FILE>-%d{yyyy-MM-dd-HH}-%i.log.gz">
Warning
|
If the system is unable to write to the |
6. Installing
Set up a complete, secure instance of DDF. For simplified steps used for a testing, development, or demonstration installation, see the DDF Quick Start.
Important
|
Although DDF can be installed by any user, it is recommended for security reasons to have a non- |
Note
|
Hardening guidance assumes a Standard installation. Adding other components does not have any security/hardening implications. |
6.1. Installation Prerequisites
Warning
|
For security reasons, DDF cannot be started from a user’s home directory. If attempted, the system will automatically shut down. |
These are the system/environment requirements to configure prior to an installation.
Note
|
The DDF process or user under which the DDF process runs must have permission to create and write files in the directories where the Solr cores are installed, If this permission is missing, DDF will not be able to create new Solr cores and the system will not function correctly. |
6.1.1. Hardware Requirements
Minimum and Recommended Requirements for DDF Systems | ||
---|---|---|
Criteria |
Minimum |
Recommended |
CPU |
Dual Core 1.6 GHz |
Quad Core 2.6 GHz |
RAM |
8 GB* |
32 GB |
Disk Space |
40 GB |
80 GB |
Video Card |
— |
WebGL capable GPU |
Additional Software |
JRE 8 x64 |
JDK 8 x64 |
*The amount of RAM can be increased to support memory-intensive applications. See Memory Considerations
DDF has been tested on the following operating systems and with the following browsers. Other operating systems or browsers may be used but have not been officially tested.
Operating Systems | Browsers |
---|---|
Windows Server 2012 R2 |
Internet Explorer 11 |
6.1.2. Java Requirements
For a runtime system:
-
JRE 8 x64 or OpenJDK 8 JRE must be installed.
-
The
JRE_HOME
environment variable must be set to the locations where the JRE is installed
For a development system:
-
JDK8 must be installed.
-
The
JAVA_HOME
environment variable must be set to the location where the JDK is installed.-
Install/Upgrade to Java 8 x64 J2SE 8 SDK
-
The recommended version is 8u60 or later.
-
Java version must contain only number values.
-
-
Install/Upgrade to JDK8 .
-
Set the
JAVA_HOME
environment variable to the location where the JDK is installed.
-
Note
|
Prior to installing DDF, ensure the system time is accurate to prevent federation issues. |
Note
|
*NIX Unset JAVA_HOME if Previously Set
Unset
|
If JDK was installed:
Replace <JAVA_VERSION>
with the version and build number installed.
-
Open a terminal window(*NIX) or command prompt (Windows) with administrator privileges.
-
Determine Java Installation Directory (This varies between operating system versions).
Find Java Path in *NIXwhich java
Find Java Path in WindowsThe path to the JDK can vary between versions of Windows, so manually verify the path under:
C:\Program Files\Java\jdk<M.m.p_build>
-
Copy path of Java installation to clipboard. (example:
/usr/java/<JAVA_VERSION
>) -
Set
JAVA_HOME
by replacing <PATH_TO_JAVA> with the copied path in this command:SettingJAVA_HOME
on *NIXJAVA_HOME=<PATH_TO_JAVA><JAVA_VERSION> export JAVA_HOME
SettingJAVA_HOME
on Windowsset JAVA_HOME=<PATH_TO_JAVA><JAVA_VERSION> setx JAVA_HOME "<PATH_TO_JAVA><JAVA_VERSION>"
AddingJAVA_HOME
toPATH
Environment Variable on Windowssetx PATH "%PATH%;%JAVA_HOME%\bin"
-
Restart or open up a new Terminal (shell) or Command Prompt to verify
JAVA_HOME
was set correctly. It is not necessary to restart the system for the changes to take effect.*NIXecho $JAVA_HOME
Windowsecho %JAVA_HOME%
If JRE was installed:
Replace <JAVA_VERSION>
with the version and build number installed.
-
Open a terminal window(*NIX) or command prompt (Windows) with administrator privileges.
-
Determine Java Installation Directory (This varies between operating system versions).
Find Java Path in *NIXwhich java
Find Java Path in WindowsThe path to the JRE can vary between versions of Windows, so manually verify the path under:
C:\Program Files\Java\jre<M.m.p_build>
-
Copy path of Java installation to clipboard. (example:
/usr/java/<JAVA_VERSION
>) -
Set
JRE_HOME
by replacing <PATH_TO_JAVA> with the copied path in this command:SettingJRE_HOME
on *NIXJRE_HOME=<PATH_TO_JAVA><JAVA_VERSION> export JRE_HOME
SettingJRE_HOME
on Windowsset JRE_HOME=<PATH_TO_JAVA><JAVA_VERSION> setx JRE_HOME "<PATH_TO_JAVA><JAVA_VERSION>"
AddingJRE_HOME
toPATH
Environment Variable on Windowssetx PATH "%PATH%;%JRE_HOME%\bin"
-
Restart or open up a new Terminal (shell) or Command Prompt to verify
JRE_HOME
was set correctly. It is not necessary to restart the system for the changes to take effect.*NIXecho $JRE_HOME
Windowsecho %JRE_HOME%
Note
|
File Descriptor Limit on Linux
fs.file-max = 6815744
*Nix Restart Command
init 6 |
6.2. Installing With the DDF Distribution Zip
Warning
|
Check System Time
Prior to installing DDF, ensure the system time is accurate to prevent federation issues. |
To install the DDF distribution zip, perform the following:
-
Download the DDF zip file .
-
After the prerequisites have been met, change the current directory to the desired install directory, creating a new directory if desired. This will be referred to as
<DDF_HOME>
.WarningWindows Pathname WarningDo not use spaces in directory or file names of the
<DDF_HOME>
path. For example, do not install in the defaultProgram Files
directory.Example: Create a Directory (Windows and *NIX)mkdir new_installation
-
Use a Non-
root
User on *NIX. (Windows users skip this step)It is recommended that the
root
user create a new install directory that can be owned by a non-root
user (e.g., DDF_USER). This can be a new or existing user. This DDF_USER can now be used for the remaining installation instructions. -
Create a new group or use an existing group (e.g., DDF_GROUP) (Windows users skip this step)
Example: Add New Group on *NIXgroupadd DDF_GROUP
Example: Switch User on *NIXchown DDF_USER:DDF_GROUP new_installation su - DDF_USER
-
-
Change the current directory to the location of the zip file (ddf-2.21.6.zip).
*NIX (Example assumes DDF has been downloaded to a CD/DVD)cd /home/user/cdrom
Windows (Example assumes DDF has been downloaded to the D drive)cd D:\
-
Copy ddf-2.21.6.zip to <DDF_HOME>.
*NIXcp ddf-2.21.6.zip <DDF_HOME>
Windowscopy ddf-2.21.6.zip <DDF_HOME>
-
Change the current directory to the desired install location.
*NIX or Windowscd <DDF_HOME>
-
The DDF zip is now located within the
<DDF_HOME>
. Unzip ddf-2.21.6.zip.*NIXunzip ddf-2.21.6.zip
WarningWindows Zip Utility WarningThe Windows Zip implementation, which is invoked when a user double-clicks on a zip file in the Windows Explorer, creates a corrupted installation. This is a consequence of its inability to process long file paths. Instead, use the java jar command line utility to unzip the distribution (see example below) or use a third party utility such as 7-Zip.
Use Java to Unzip in Windows(Replace<PATH_TO_JAVA>
with correct pathand <JAVA_VERSION>
with current version.)"<PATH_TO_JAVA>\jdk<JAVA_VERSION>\bin\jar.exe" xf ddf-2.21.6.zip
The unzipping process may take time to complete. The command prompt will stop responding to input during this time.
6.2.1. Configuring Operating Permissions and Allocations
Restrict access to sensitive files by ensuring that the only users with access privileges are administrators.
Within the <DDF_HOME>
, a directory is created named ddf-2.21.6.
This directory will be referred to in the documentation as <DDF_HOME>
.
-
Do not assume the deployment is from a trusted source; verify its origination.
-
Check the available storage space on the system to ensure the deployment will not exceed the available space.
-
Set maximum storage space on the
<DDF_HOME>/deploy
and<DDF_HOME>/system
directories to restrict the amount of space used by deployments.
6.2.1.1. Setting Directory Permissions
-
Required Step for Security Hardening
DDF relies on the Directory Permissions of the host platform to protect the integrity of the DDF during operation. System administrators MUST perform the following steps prior to deploying bundles added to the DDF.
Important
|
The system administrator must restrict certain directories to ensure that the application (user) cannot access restricted directories on the system.
For example the |
6.2.1.2. Configuring Memory Allocation for the DDF Java Virtual Machine
The amount of memory allocated to the Java Virtual Machine host DDF by the operating
system can be increased by updating the setenv
script:
<DDF_HOME>/bin/setenv Update the JAVA_OPTS -Xmx value <DDF_HOME>/bin/setenv-wrapper.conf Update the wrapper.java.additional -Xmx value
<DDF_HOME>/bin/setenv.bat Update the JAVA_OPTS -Xmx value <DDF_HOME>/bin/setenv-windows-wrapper.conf Update the wrapper.java.additional -Xmx value
6.2.1.3. Enabling JMX
By default, DDF prevents connections to JMX because the system is more secure when JMX is not enabled. However, many monitoring tools require a JMX connection to the Java Virtual Machine. To enable JMX, update the setenv script:
<DDF_HOME>/bin/setenv Remove -XX:+DisableAttachMechanism from JAVA_OPTS <DDF_HOME>/bin/setenv-wrapper.conf Comment out the -XX:+DisableAttachMechanism line and re-number remainder lines appropriately
<DDF_HOME>/bin/setenv.bat Remove -XX:+DisableAttachMechanism from JAVA_OPTS <DDF_HOME>/bin/setenv-windows-wrapper.conf Comment out the -XX:+DisableAttachMechanism line and re-number remainder lines appropriately
6.2.1.4. Configuring Memory for the Solr Server
Note
|
This section applies only to configurations that manage the lifecycle of the Solr server. It does not apply to Solr Cloud configurations. |
The Solr server consumes large amount of memory when it ingests documents. If the Solr server
runs out of memory, it terminates its process. To allocate more memory to the Solr server,
increase the value of the solr.mem
property.
6.2.2. Managing Keystores and Certificates
-
Required Step for Security Hardening
DDF uses certificates in two ways:
-
Ensuring the privacy and integrity of messages sent or received over a network.
-
Authenticating an incoming user request.
To ensure proper configuration of keystore, truststore, and certificates, follow the options below according to situation.
Jump to the steps referenced in the diagram:
6.2.2.1. Managing Keystores
Certificates, and sometimes their associated private keys, are stored in keystore files. DDF includes two default keystore files, the server key store and the server trust store. The server keystore holds DDF’s certificate and private key. It will also hold the certificates of other nodes whose signature DDF will accept. The truststore holds the certificates of nodes or other entities that DDF needs to trust.
Note
|
Individual certificates of other nodes should be added to the keystore instead of CA certificates. If a CA’s certificate is added, DDF will automatically trust any certificate that is signed by that CA. |
6.2.2.1.1. Adding an Existing Server Keystore
If provided an existing keystore for use with DDF, follow these steps to replace the default keystore.
-
Remove the default keystore at
etc/keystores/serverKeystore.jks
. -
Add the desired keystore file to the
etc/keystores
directory. -
Edit
custom.system.properties
file to set filenames and passwords.-
If using a type of keystore other than
jks
(such aspkcs12
), change thejavax.net.ssl.keyStoreType
property as well.
-
-
If the truststore has the correct certificates, restart server to complete configuration.
-
If provided with an existing server truststore, continue to Adding an Existing Server Truststore.
-
Otherwise, create a server truststore.
-
6.2.2.1.2. Adding an Existing Server Truststore
-
Remove the default truststore at
etc/keystores/serverTruststore.jks
. -
Add the desired truststore file to the
etc/keystores
directory. -
Edit
custom.system.properties
file to set filenames and passwords.-
If using a type of truststore other than
jks
(such aspkcs12
), change thejavax.net.ssl.trustStoreType
property as well.
-
If the provided server keystore does not include the CA certificate that was used to sign the server’s certificate, add the CA certificate into the serverKeystore
file.
6.2.2.1.3. Creating a New Keystore/Truststore with an Existing Certificate and Private Key
If provided an existing certificate, create a new keystore and truststore with it.
Note
|
DDF requires that the keystore contains both the private key and the CA. |
-
Using the private key, certificate, and CA certificate, create a new keystore containing the data from the new files.
cat client.crt >> client.key openssl pkcs12 -export -in client.key -out client.p12 keytool -importkeystore -srckeystore client.p12 -destkeystore serverKeystore.jks -srcstoretype pkcs12 -alias 1 keytool -changealias -alias 1 -destalias client -keystore serverKeystore.jks keytool -importcert -file ca.crt -keystore serverKeystore.jks -alias "ca" keytool -importcert -file ca-root.crt -keystore serverKeystore.jks -alias "ca-root"
-
Create the truststore using only the CA certificate. Based on the concept of CA signing, the CA should be the only entry needed in the truststore.
keytool -import -trustcacerts -alias "ca" -file ca.crt -keystore truststore.jks keytool -import -trustcacerts -alias "ca-root" -file ca-root.crt -keystore truststore.jks
-
Create a PEM file using the certificate, as some applications require that format.
openssl x509 -in client.crt -out client.der -outform DER openssl x509 -in client.der -inform DER -out client.pem -outform PEM
Important
|
The localhost certificate must be removed if using a system certificate. |
6.2.2.1.4. Updating Key Store / Trust Store via the Admin Console
Certificates (and certificates with keys) can be managed in the Admin Console.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Certificates tab.
-
Add and remove certificates and private keys as necessary.
-
Restart DDF.
Important
|
The default trust store and key store files for DDF included in |
This view shows the alias (name) of every certificate in the trust store and the key store. It also displays if the entry includes a private key ("Is Key") and the encryption scheme (typically "RSA" or "EC").
This view allows administrators remove certificates from DDF’s key and trust stores. It also allows administrators to import certificates and private keys into the keystores with the "+" button. The import function has two options: import from a file or import over HTTPS. The file option accepts a Java Keystore file or a PKCS12 keystore file. Because keystores can hold many keys, the import dialog asks the administrator to provide the alias of the key to import. Private keys are typically encrypted and the import dialog prompts the administrator to enter the password for the private key. Additionally, keystore files themselves are typically encrypted and the dialog asks for the keystore ("Store") password.
The name and location of the DDF trust and key stores can be changed by editing the system properties files, etc/custom.system.properties
.
Additionally, the password that DDF uses to decrypt (unlock) the key and trust stores can be changed here.
Important
|
DDF assumes that password used to unlock the keystore is the same password that unlocks private keys in the keystore. |
The location, file name, passwords and type of the server and trust key stores can be set in the custom.system.properties
file:
-
Setting the Keystore and Truststore Java Properties
javax.net.ssl.keyStore=etc/keystores/serverKeystore.jks javax.net.ssl.keyStorePassword=changeit javax.net.ssl.trustStore=etc/keystores/serverTruststore.jks javax.net.ssl.trustStorePassword=changeit javax.net.ssl.keyStoreType=jks javax.net.ssl.trustStoreType=jks
Note
|
If the server’s fully qualified domain name is not recognized, the name may need to be added to the network’s DNS server. |
Tip
|
The DDF instance can be tested even if there is no entry for the FQDN in the DNS. First, test if the FQDN is already recognized. Execute this command:
If the command responds with an error message such as unknown host, then modify the system’s
|
Note
|
Changing Default Passwords
This step is not required for a hardened system.
|
6.3. Initial Startup
Run the DDF using the appropriate script.
<DDF_HOME>/bin/ddf
<DDF_HOME>/bin/ddf.bat
The distribution takes a few moments to load depending on the hardware configuration.
Tip
|
To run DDF as a service, see Starting as a Service. |
6.3.1. Verifying Startup
At this point, DDF should be configured and running with a Solr Catalog Provider. New features (endpoints, services, and sites) can be added as needed.
Verification is achieved by checking that all of the DDF bundles are in an Active state (excluding fragment bundles which remain in a Resolved state).
Note
|
It may take a few moments for all bundles to start so it may be necessary to wait a few minutes before verifying installation. |
Execute the following command to display the status of all the DDF bundles:
ddf@local>list | grep -i ddf
Warning
|
Entries in the Resolved state are expected, they are OSGi bundle fragments.
Bundle fragments are distinguished from other bundles in the command line console list by a field named |
96 | Resolved | 80 | 2.10.0.SNAPSHOT | DDF :: Platform :: PaxWeb :: Jetty Config, Hosts: 90
After successfully completing these steps, the DDF is ready to be configured.
6.3.2. DDF Directory Contents after Installation and Initial Startup
During DDF installation, the major directories and files shown in the table below are created, modified, or replaced in the destination directory.
Directory Name | Description |
---|---|
|
Scripts to start, stop, and connect to DDF. |
|
The working directory of the system – installed bundles and their data |
|
Log file for DDF, logging all errors, warnings, and (optionally) debug statements. This log rolls up to 10 times, frequency based on a configurable setting (default=1 MB) |
|
Log file for any ingest errors that occur within DDF. |
|
Log file that records user interactions with the system for auditing purposes. |
|
Hot-deploy directory – KARs and bundles added to this directory will be hot-deployed (Empty upon DDF installation) |
|
HTML and PDF copies of DDF documentation. |
|
Directory monitored for addition/modification/deletion of |
|
Template |
|
The system’s bootstrap libraries. Includes the |
|
Licensing information related to the system. |
|
Apache Solr server used when DDF manages Solr |
|
Log file for Solr. |
|
Local bundle repository. Contains all of the JARs required by DDF, including third-party JARs. |
6.3.3. Completing Installation
Upon startup, complete installation from either the Admin Console or the Command Console.
6.3.3.1. Completing Installation from the Admin Console
Upon startup, the installation can be completed by navigating to the Admin Console at https://{FQDN}:{PORT}/admin.
Warning
|
Internet Explorer 10 TLS Warning
Internet Exlorer 10 users may need to enable TLS 1.2 to access the Admin Console in the browser. Enabling TLS1.2 in IE10
|
-
Default user/password:
admin
/admin
.
On the initial startup of the Admin Console, a series of prompts walks through essential configurations. These configurations can be changed later, if needed.
-
Click Start to begin.
6.3.3.2. Completing Installation from the Command Console
In order to install DDF from the Command Console, use the command profile:install <profile-name>
.
The <profile-name>
should be the desired Setup Type in lowercase letters.
To see the available profiles, use the command profile:list
.
Note
|
This only installs the desired Setup Type. There are other components that can be set up in the Admin Console Installer that cannot be setup on the Command Console. After installing the Setup Type, these other components can be set up as described below. |
6.3.3.2.1. Configuring Guest Claim Attributes
The Guest Claim Attributes can be configured via the Admin Console after running the profile:install
command.
See Configuring Guest Claim Attributes.
6.3.3.2.2. System Configuration Settings
System Settings and Contact Info, as described in System Configuration Settings, can be changed in <DDF_HOME>/etc/custom.system.properties
.
The certificates must be set up manually as described in Managing Keystores and Certificates.
Note
|
The system will need to be restarted after changing any of these settings. |
6.3.4. Firewall Port Configuration
Below is a table listing all of the default ports that DDF uses and a description of what they are used for. Firewalls will need to be configured to open these ports in order for external systems to communicate with DDF.
Port | Usage description |
---|---|
8993 |
https access to DDF admin and search web pages. |
8101 |
For administering DDF instances gives ssh access to the administration console. |
1099 |
RMI Registry Port |
44444 |
RMI Server Port |
8994 |
Solr Server Port. DDF does not listen on this port, but the Solr process does and it must be able to receive requests from DDF on this port. |
Note
|
These are the default ports used by DDF. DDF can be configured to use different ports. |
6.3.5. Internet Explorer 11 Enhanced Security Configuration
Below are steps listing all of the changes that DDF requires to run on Internet Explorer 11 and several additional considerations to keep in mind.
-
In the IE11
Settings
>Compatibility View Settings
dialog, un-checkDisplay intranet sites in Compatibility View
. -
In the
Settings
>Internet Options
>Security
tab,Local intranet
zone:-
Click the
Sites
>Advanced
button, add the current host name to the list, e.g., https://windows-host-name.domain.edu, and close the dialog. -
Make sure the security level for the
Local intranet
zone is set toMedium-low
inCustom level…
.-
Enable Protected Mode
is checked by default, but it may need to be disabled if the above changes do not fully resolve access issues.
-
-
-
Restart the browser.
Note
|
During installation, make sure to use the host name and not localhost when setting up the DDF’s hostname, port, etc. |
6.4. High Availability Initial Setup
This section describes how to complete the initial setup of DDF in a Highly Available Cluster.
-
A failover proxy that can route HTTP traffic according to the pattern described in the Introduction to High Availability. It is recommended that a hardware failover proxy be used in a production environment.
-
Solr Cloud: See the Solr Cloud section for installation and configuration guidance to connect DDF nodes to Solr Cloud.
Once the prerequisites have been met, the below steps can be followed.
Note
|
Unless listed in the High Availability Initial Setup Exceptions section, the normal steps can be followed for installing, configuring, and hardening. |
-
Install the first DDF node. See the Installation Section.
-
Configure the first DDF node. See the Configuring Section.
-
Optional: If hardening the first DDF node (excluding setting directory permissions). See the Hardening Section.
-
Export the first DDF node’s configurations, install the second DDF node, and import the exported configurations on that node. See Reusing Configurations.
-
If hardening, set directory permissions on both DDF nodes. See Setting Directory Permissions.
6.4.1. High Availability Initial Setup Exceptions
These steps are handled differently for the initial setup of a Highly Available Cluster.
6.4.1.1. Failover Proxy Integration
In order to integrate with a failover proxy, the DDF node’s system properties (in <DDF_HOME>/etc/custom.system.properties
) must be changed to publish the correct port to external systems and users.
This must be done before installing the first DDF node. See High Availability Initial Setup.
There are two internal port properties that must be changed to whatever ports the DDF will use on its system. Then there are two external port properties that must be changed to whatever ports the failover proxy is forwarding traffic through.
Warning
|
Make sure that the failover proxy is already running and forwarding traffic on the chosen ports before starting the DDF. There may be unexpected behavior otherwise. |
In the below example, the failover proxy with a hostname of service.org is forwarding https traffic via 8993 and http traffic via 8181. The DDF node will run on 1111 for https and 2222 for http (on the host that it’s hosted on). The hostname of the DDF must match the hostname of the proxy.
org.codice.ddf.system.hostname=service.org
org.codice.ddf.system.httpsPort=1111
org.codice.ddf.system.httpPort=2222
org.codice.ddf.system.port=${org.codice.ddf.system.httpsPort}
org.codice.ddf.external.hostname=service.org
org.codice.ddf.external.httpsPort=8993
org.codice.ddf.external.httpPort=8181
org.codice.ddf.external.port=${org.codice.ddf.external.httpsPort}
6.4.1.2. Identical Directory Structures
The two DDF nodes need to be under identical root directories on their corresponding systems. On Windows, this means they must be under the same drive.
6.4.1.3. Highly Available Security Auditing
A third party tool will have to be used to persist the logs in a highly available manner.
-
Edit the
<DDF_HOME>/etc/org.ops4j.pax.logging.cfg
file to enable log4j2, following the steps in Enabling Fallback Audit Logging. -
Then put the appropriate log4j2 appender in
<DDF_HOME>/etc/log4j2.xml
to send logs to the chosen third party tool. See Log4j Appenders .
6.4.1.4. Shared Storage Provider
The storage provider must be in a location that is shared between the two DDF nodes and must be highly available. If hardening the Highly Available Cluster, this shared storage provider must be trusted/secured. One way to accomplish this is to use the default Content File System Storage Provider and configure it to point to a highly available shared directory.
6.4.1.5. High Availability Certificates
Due to the nature of highly available environments, localhost is not suitable for use as a hostname to identify the DDF cluster. The default certificate that ships with the product uses localhost as the common name, so this certificate needs to be replaced. The following describes how to generate a certificate signed by the DDF Demo Certificate Authority that uses a proper hostname.
Note
|
This certificate, and any subsequent certificates signed by the Demo CA, are intended for testing purposes only, and should not be used in production. |
Certificates need to have Subject Alternative Names (SANs) which will include the host for the failover
proxy and for both DDF nodes. A certificate with SANs signed by the Demo CA can be obtained by
navigating to <DDF_HOME>/etc/certs/
and, assuming the proxy’s hostname is service.org, running
the following for UNIX operating systems:
./CertNew.sh -cn service.org -san "DNS:service.org"
or the following for Windows operating systems:
CertNew -cn service.org -san "DNS:service.org"
Note
|
Systems that use DDF version 2.11.4 or later will automatically get a DNS SAN entry matching the CN
without the need to specify the |
More customization for certs can be achieved by following the steps at Creating New Server Keystore Entry with the CertNew Scripts.
6.4.1.6. High Availability Installation Profile
Instead of having to manually turn features on and off, there is a High Availability installation profile.
This profile will not show up in the UI Installer, but can be installed by executing profile:install ha
on the command line instead of stepping through the UI Installer.
This profile will install all of the High Availability supported features.
7. Configuring
DDF is highly configurable and many of the components of the system can be configured to use an included DDF implementation or replaced with an existing component of an integrating system.
Note
|
Configuration Requirements
Because components can easily be installed and uninstalled, it’s important to remember that for proper DDF functionality, at least the Catalog API, one Endpoint, and one Catalog Framework implementation must be active. |
DDF provides several tools for configuring the system.
The Admin Console is a useful interface for configuring applications, their features, and important settings.
Alternatively, many configurations can be updated through console commands entered into the Command Console.
Finally, configurations are stored in configuration files within the <DDF_HOME>
directory.
While many configurations can be set or changed in any order, for ease of use of this documentation, similar subjects have been grouped together sequentially.
See Keystores and certificates to set up the certificates needed for messaging integrity and authentication. Set up Users with security attributes, then configure data attribute handling, and finally, define the Security Policies that map between users and data and make decisions about access.
Connecting DDF to other data sources, including other instances of DDF is covered in the Configuring Federation section.
Lastly, see the Configuring for Special Deployments section for guidance on common specialized installations, such as fanout or multiple identical configurations.
7.1. Admin Console Tutorial
The Admin Console is the centralized location for administering the system. The Admin Console allows an administrator to configure and tailor system services and properties. The default address for the Admin Console is https://{FQDN}:{PORT}/admin.
The configuration and features installed can be viewed and edited from the System tab of the Admin Console.
It is recommended to use the Catalog App → Sources tab to configure and manage sites/sources.
DDF displays all active applications in the Admin Console.
This view can be configured according to preference.
Either view has an >
arrow icon to view more information about the application as currently configured.
View | Description |
---|---|
Tile View |
The first view presented is the Tile View, displaying all active applications as individual tiles. |
List View |
Optionally, active applications can be displayed in a list format by clicking the list view button. |
Each individual application has a detailed view to modify configurations specific to that application. All applications have a standard set of tabs, although some apps may have additional ones with further information.
Tab | Explanation |
---|---|
Configuration |
The Configuration tab lists all bundles associated with the application as links to configure any configurable properties of that bundle. |
DDF includes many components, packaged as features, that can be installed and/or uninstalled without restarting the system. Features are collections of OSGi bundles, configuration data, and/or other features.
Note
|
Transitive Dependencies
Features may have dependencies on other features and will auto-install them as needed. |
In the Admin Console, Features are found on the Features tab of the System tab.
-
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Uninstalled features are shown with a play arrow under the Actions column.
-
Select the play arrow for the desired feature.
-
The Status will change from Uninstalled to Installed.
-
-
Installed features are shown with a stop icon under the Actions column.
-
Select the stop icon for the desired feature.
-
The Status will change from Installed to Uninstalled.
-
7.2. Console Command Reference
DDF provides access to a powerful Command Console to use to manage and configure the system.
7.2.1. Feature Commands
Individual features can also be added via the Command Console.
-
Determine which feature to install by viewing the available features on DDF.
ddf@local>feature:list
-
The console outputs a list of all features available (installed and uninstalled). A snippet of the list output is shown below (the versions may differ):
State Version Name Repository Description [installed ] [2.21.6 ] security-handler-api security-services-app-2.21.6 API for authentication handlers for web applications. [installed ] [2.21.6 ] security-core security-services-app-2.21.6 DDF Security Core [uninstalled] [2.21.6 ] security-expansion security-services-app-2.21.6 DDF Security Expansion [installed ] [2.21.6 ] security-pdp-authz security-services-app-2.21.6 DDF Security PDP. [uninstalled] [2.21.6 ] security-pep-serviceauthz security-services-app-2.21.6 DDF Security PEP Service AuthZ [uninstalled] [2.21.6 ] security-expansion-user-attributes security-services-app-2.21.6 DDF Security Expansion User Attributes Expansion [uninstalled] [2.21.6 ] security-expansion-metacard-attributes security-services-app-2.21.6 DDF Security Expansion Metacard Attributes Expansion [installed ] [2.21.6 ] security-sts-server security-services-app-2.21.6 DDF Security STS. [installed ] [2.21.6 ] security-sts-realm security-services-app-2.21.6 DDF Security STS Realm. [uninstalled] [2.21.6 ] security-sts-ldaplogin security-services-app-2.21.6 DDF Security STS JAAS LDAP Login. [uninstalled] [2.21.6 ] security-sts-ldapclaimshandler security-services-app-2.21.6 Retrieves claims attributes from an LDAP store.
-
Check the bundle status to verify the service is started.
ddf@local>list
The console output should show an entry similar to the following:
[ 117] [Active ] [ ] [Started] [ 75] DDF :: Catalog :: Source :: Dummy (<version>)
7.2.1.1. Uninstalling Features from the Command Console
-
Check the feature list to verify the feature is installed properly.
ddf@local>feature:list
State Version Name Repository Description [installed ] [2.21.6 ] ddf-core ddf-2.21.6 [uninstalled] [2.21.6 ] ddf-sts ddf-2.21.6 [installed ] [2.21.6 ] ddf-security-common ddf-2.21.6 [installed ] [2.21.6 ] ddf-resource-impl ddf-2.21.6 [installed ] [2.21.6 ] ddf-source-dummy ddf-2.21.6
-
Uninstall the feature.
ddf@local>feature:uninstall ddf-source-dummy
Warning
|
Dependencies that were auto-installed by the feature are not automatically uninstalled. |
-
Verify that the feature has uninstalled properly.
ddf@local>feature:list
State Version Name Repository Description [installed ] [2.21.6 ] ddf-core ddf-2.21.6 [uninstalled] [2.21.6 ] ddf-sts ddf-2.21.6 [installed ] [2.21.6 ] ddf-security-common ddf-2.21.6 [installed ] [2.21.6 ] ddf-resource-impl ddf-2.21.6 [uninstalled] [2.21.6 ] ddf-source-dummy ddf-2.21.6
7.3. Configuration Files
Many important configuration settings are stored in the <DDF_HOME>
directory.
Note
|
Depending on the environment, it may be easier for integrators and administrators to configure DDF using the Admin Console prior to disabling it for hardening purposes. The Admin Console can be re-enabled for additional configuration changes. |
In an environment hardened for security purposes, access to the Admin Console or the Command Console might be denied and using the latter in such an environment may cause configuration errors.
It is necessary to configure DDF (e.g., providers, Schematron rulesets, etc.) using .config
files.
A template file is provided for some configurable DDF items so that they can be copied/renamed then modified with the appropriate settings.
Warning
|
If the Admin Console is enabled again, all of the configuration done via |
7.3.1. Configuring Global Settings with custom.system.properties
Global configuration settings are configured via the properties file custom.system.properties
.
These properties can be manually set by editing this file or set via the initial configuration from the Admin Console.
Note
|
Any changes made to this file require a restart of the system to take effect. |
Important
|
The passwords configured in this section reflect the passwords used to decrypt JKS (Java KeyStore) files. Changing these values without also changing the passwords of the JKS causes undesirable behavior. |
Title | Property | Type | Description | Default Value | Required |
---|---|---|---|---|---|
Keystore and Truststore Java Properties |
|||||
Keystore |
|
String |
Path to server keystore |
|
Yes |
Keystore Password |
|
String |
Password for accessing keystore |
|
Yes |
Truststore |
|
String |
The trust store used for SSL/TLS connections. Path is relative to |
|
Yes |
Truststore Password |
|
String |
Password for server Truststore |
|
Yes |
Keystore Type |
|
String |
File extension to use with server keystore |
|
Yes |
Truststore Type |
|
String |
File extension to use with server truststore |
|
Yes |
Headless mode |
|||||
Headless Mode |
|
Boolean |
Force java to run in headless mode for when the server doesn’t have a display device |
|
No |
Global URL Properties |
|||||
Internal Default Protocol |
|
String |
Default protocol that should be used to connect to this machine. |
|
Yes |
Internal Host |
|
String |
The hostname or IP address this system runs on. If the hostname is changed during the install to something other than |
|
Yes |
Internal HTTPS Port |
|
String |
The https port that the system uses. NOTE: This DOES change the port the system runs on. |
|
Yes |
Internal HTTP Port |
|
String |
The http port that the system uses. NOTE: This DOES change the port the system runs on. |
|
Yes |
Internal Default Port |
|
String |
The default port that the system uses. This should match either the above http or https port. NOTE: This DOES change the port the system runs on. |
|
Yes |
Internal Root Context |
|
String |
The base or root context that services will be made available under. |
|
Yes |
External Default Protocol |
|
String |
Default protocol that should be used to connect to this machine. |
|
Yes |
External Host |
|
String |
The hostname or IP address used to advertise the system. Do not enter If the hostname is changed during the install to something other than NOTE: Does not change the address the system runs on. |
|
Yes |
HTTPS Port |
|
String |
The https port used to advertise the system. NOTE: This does not change the port the system runs on. |
|
Yes |
External HTTP Port |
|
String |
The http port used to advertise the system. NOTE: This does not change the port the system runs on. |
|
Yes |
External Default Port |
|
String |
The default port used to advertise the system. This should match either the above http or https port. NOTE: Does not change the port the system runs on. |
|
Yes |
External Root Context |
|
String |
The base or root context that services will be advertised under. |
|
Yes |
System Information Properties |
|||||
Site Name |
|
String |
The site name for DDF. |
|
Yes |
Site Contact |
|
String |
The email address of the site contact. |
No |
|
Version |
|
String |
The version of DDF that is running. This value should not be changed from the factory default. |
|
Yes |
Organization |
|
String |
The organization responsible for this installation of DDF. |
|
Yes |
Registry ID |
|
String |
The registry id for this installation of DDF. |
No |
|
Thread Pool Settings |
|||||
Thread Pool Size |
|
Integer |
Size of thread pool used for handling UI queries, federating requests, and downloading resources. See Configuring Thread Pools |
|
Yes |
HTTPS Specific Settings |
|||||
Cipher Suites |
|
String |
Cipher suites to use with secure sockets. If using the JCE unlimited strength policy, use this list in place of the defaults: . |
|
No |
Https Protocols |
|
String |
Protocols to allow for secure connections |
|
No |
Allow Basic Auth Over Http |
|
Boolean |
Set to true to allow Basic Auth credentials to be sent over HTTP unsecurely. This should only be done in a test environment. These events will be audited. |
|
Yes |
Restrict the Security Token Service to allow connections only from DNs matching these patterns |
|
String |
Set to a comma separated list of regex patterns to define which hosts are allowed to connect to the STS |
|
Yes |
XML Settings |
|||||
Parse XML documents into DOM object trees |
|
String |
Enables Xerces-J implementation of |
|
Yes |
Catalog Source Retry Interval |
|||||
Initial Endpoint Contact Interval |
|
Integer |
If a Catalog Source is unavailable, try to connect to it after the initial interval has elapsed. After every retry, the interval doubles, up to a given maximum interval. The interval is measured in seconds. |
|
Yes |
Maximum Endpoint Contact Interval |
|
Integer |
Do not wait longer than the maximum interval to attempt to establish a connection with an unavailable Catalog Source. Smaller values result in more current information about the status of Catalog Sources, but cause more network traffic. The interval is measured in seconds. |
|
Yes |
File Upload Settings |
|||||
File extensions flagged as potentially dangerous to the host system or external clients |
|
String |
Files uploaded with these bad file extensions will have their file names sanitized before being saved E.g. sample_file.exe will be renamed to sample_file.bin upon ingest |
|
Yes |
File names flagged as potentially dangerous to the host system or external clients |
|
String |
Files uploaded with these bad file names will have their file names sanitized before being saved E.g. crossdomain.xml will be renamed to file.bin upon ingest |
|
Yes |
Mime types flagged as potentially dangerous to external clients |
|
String |
Files uploaded with these mime types will be rejected from the upload |
|
Yes |
File names flagged as potentially dangerous to external clients |
|
String |
Files uploaded with these file names will be rejected from the upload |
|
Yes |
|
String |
Type of Solr configuration |
|
Yes |
|
Solr Cloud Properties |
|||||
Zookeeper Nodes |
|
String |
Zookeeper hostnames and port numbers |
|
Yes |
Allow DDF to change the Solr server password if it detects the default password is in use |
|
Boolean |
If true, DDF attempts to change the default Solr server password to a randomly
generated UUID. This property is only used if the |
|
Yes |
Solr Data Directory |
|
String |
Directory for Solr core files |
|
Yes |
Solr server HTTP port |
|
Integer |
Solr server’s port. |
|
Yes |
|
String |
URL for a HTTP Solr server (required for HTTP Solr) |
|
Yes |
|
Solr Heap Size |
|
String |
Memory allocated to the Solr Java process |
|
Yes |
|
String |
The password used for basic authentication to Solr. This property is only used if the
|
|
Yes |
|
|
String |
The username for basic authentication to Solr. This property is only used if the
|
|
Yes |
|
|
Boolean |
If true, the HTTP Solr Client sends a username and password when sending requests to Solr server.
This property is only used if the |
|
Yes |
|
Start Solr server |
|
Boolean |
If true, application manages Solr server lifecycle |
|
Yes |
These properties are available to be used as variable parameters in input url fields within the Admin Console. For example, the url for the local csw service (https://{FQDN}:{PORT}/services/csw) could be defined as:
${org.codice.ddf.system.protocol}${org.codice.ddf.system.hostname}:${org.codice.ddf.system.port}${org.codice.ddf.system.rootContext}/csw
This variable version is more verbose, but will not need to be changed if the system host
, port
or root
context changes.
Warning
|
Only root can access ports < 1024 on Unix systems. |
7.3.2. Configuring with .config Files
The DDF is configured using .config
files.
Like the Karaf .cfg
files, these configuration files must be located in the <DDF_HOME>/etc/
directory.
Unlike the Karaf .cfg
files, .config
files must follow the naming convention that includes the configuration persistence ID (PID) that they represent.
The filenames must be the pid with a .config
extension.
This type of configuration file also supports lists within configuration values (metatype cardinality
attribute greater than 1) and String, Boolean, Integer, Long, Float, and Double values.
Important
|
This new configuration file format must be used for any configuration that makes use of lists.
Examples include Web Context Policy Manager ( |
Warning
|
Only one configuration file should exist for any given PID.
The result of having both a |
The main purpose of the configuration files is to allow administrators to pre-configure DDF without having to use the Admin Console.
In order to do so, the configuration files need to be copied to the <DDF_HOME>/etc
directory after DDF zip has been extracted.
Upon start up, all the .config
files located in <DDF_HOME>/etc
are automatically read and processed.
DDF monitors the <DDF_HOME>/etc
directory for any new .config
file that gets added.
As soon as a new file is detected, it is read and processed.
Changes to these configurations from the Admin Console or otherwise are persisted in the original configuration file in the <DDF_HOME>/etc
directory.
7.4. Configuring User Access
DDF does not define accounts or types of accounts to support access. DDF uses an attribute based access control (ABAC) model. For reference, ABAC systems control access by evaluating rules against the attributes of the entities (subject and object), actions, and the environment relevant to a request.
DDF can be configured to access many different types of user stores to manage and monitor user access.
7.4.1. Configuring Guest Access
Unauthenticated access to a secured DDF system is provided by the Guest user. By default, DDF allows guest access.
Because DDF does not know the identity of a Guest user, it cannot assign security attributes to the Guest. The administrator must configure the attributes and values (i.e. the "claims") to be assigned to Guests. The Guest Claims become the default minimum attributes for every user, both authenticated and unauthenticated. Even if a user claim is more restrictive, the guest claim will grant access, so ensure the guest claim is only as permissive as necessary.
The Guest user is uniquely identified with a Principal name of the format Guest@UID
. The unique
identifier is assigned to a Guest based on its source IP address and is cached so that subsequent
Guest accesses from the same IP address within a 30-minute window will get the same unique identifier.
To support administrators' need to track the source IP Address for a given Guest user, the IP Address
and unique identifier mapping will be audited in the security log.
-
Make sure that all the default logical names for locations of the security services are defined.
7.4.1.1. Denying Guest User Access
To disable guest access for a context, use the Web Context Policy Manager configuration to remove Guest. from the Authentication Type for that context. Only authorized users are then allowed to continue to the Search UI page.
Note
|
If using the included IdP for authentication, disable the |
7.4.1.2. Allowing Guest User Access
Guest authentication must be enabled and configured to allow guest users. Once the guest user is configured, redaction and filtering of metadata is done for the guest user the same way it is done for normal users.
To enable guest authentication for a context, use the Web Context Policy Manager configuration to select Allow Guest Access.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select Web Context Policy Manager.
-
Select Allow Guest Access
7.4.1.2.1. Configuring Guest Interceptor if Allowing Guest Users
-
Required Step for Security Hardening
If a legacy client requires the use of the secured SOAP endpoints, the guest interceptor should be configured.
Otherwise, the guest interceptor and public
endpoints should be uninstalled for a hardened system.
To uninstall the guest interceptor and public
endpoints:
. Navigate to the Admin Console.
. Select the System tab.
. Open the Features section.
. Search for security-interceptor-guest.
. Click the Uninstall button.
7.4.1.2.2. Configuring Guest Claim Attributes
A guest user’s attributes define the most permissive set of claims for an unauthenticated user.
A guest user’s claim attributes are stored in configuration, not in the LDAP as normal authenticated users' attributes are.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select the Security Guest Claims Handler.
-
Add any additional attributes desired for the guest user.
-
Save changes.
7.4.2. Configuring REST Services for Users
If using REST services or connecting to REST sources, several configuration options are available.
DDF includes an Identity Provider (IdP), but can also be configured to support an external IdP or no IdP at all. The following diagram shows the configuration options.
7.4.2.1. Configuring Included Identity Provider
The included IdP is installed by default.
-
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Install
security-idp
feature.
Run the command feature:install security-idp
from the Command Console.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select IdP Server.
-
Configure Authentication Request requirements
-
Disable the Require Signed AuthnRequests option to allow processing of authentication requests without signatures.
-
Disable the Limit RelayStates to 80 Bytes option to allow interoperability with Service Providers that are not compliant with the SAML Specifications and send RelayStates larger than 80 bytes.
-
-
Configure Guest Access:
-
Disable the Allow Guest Access option to disallow a user to authenticate against the IdP with a guest account.
-
-
Configure the Service Providers (SP) Metadata:
-
Select the
+
next to SP Metadata to add a new entry. -
Populate the new entry with:
-
an HTTPS URL (https://) such as https://localhost:8993/services/saml/sso/metadata1,
-
a file URL (file:), or
-
an XML block to refer to desired metadata.
-
-
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://localhost:8993/services/saml">
<md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIIDEzCCAnygAwIBAgIJAIzc4FYrIp9mMA0GCSqGSIb3DQEBBQUAMHcxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJBWjEMMAoGA1UECgwDRERGMQwwCgYDVQQLDANEZXYxGTAXBgNVBAMMEERERiBEZW1vIFJvb3QgQ0ExJDAiBgkqhkiG9w0BCQEWFWRkZnJvb3RjYUBleGFtcGxlLm9yZzAeFw0xNDEyMTAyMTU4MThaFw0xNTEyMTAyMTU4MThaMIGDMQswCQYDVQQGEwJVUzELMAkGA1UECAwCQVoxETAPBgNVBAcMCEdvb2R5ZWFyMQwwCgYDVQQKDANEREYxDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJbG9jYWxob3N0MSQwIgYJKoZIhvcNAQkBFhVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMeCyNZbCTZphHQfB5g8FrgBq1RYzV7ikVw/pVGkz8gx3l3A99s8WtA4mRAeb6n0vTR9yNBOekW4nYOiEOq//YTi/frI1kz0QbEH1s2cI5nFButabD3PYGxUSuapbc+AS7+Pklr0TDI4MRzPPkkTp4wlORQ/a6CfVsNr/mVgL2CfAgMBAAGjgZkwgZYwCQYDVR0TBAIwADAnBglghkgBhvhCAQ0EGhYYRk9SIFRFU1RJTkcgUFVSUE9TRSBPTkxZMB0GA1UdDgQWBBSA95QIMyBAHRsd0R4s7C3BreFrsDAfBgNVHSMEGDAWgBThVMeX3wrCv6lfeF47CyvkSBe9xjAgBgNVHREEGTAXgRVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwDQYJKoZIhvcNAQEFBQADgYEAtRUp7fAxU/E6JD2Kj/+CTWqu8Elx13S0TxoIqv3gMoBW0ehyzEKjJi0bb1gUxO7n1SmOESp5sE3jGTnh0GtYV0D219z/09n90cd/imAEhknJlayyd0SjpnaL9JUd8uYxJexy8TJ2sMhsGAZ6EMTZCfT9m07XduxjsmDz0hlSGV0=
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor use="encryption">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIIDEzCCAnygAwIBAgIJAIzc4FYrIp9mMA0GCSqGSIb3DQEBBQUAMHcxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJBWjEMMAoGA1UECgwDRERGMQwwCgYDVQQLDANEZXYxGTAXBgNVBAMMEERERiBEZW1vIFJvb3QgQ0ExJDAiBgkqhkiG9w0BCQEWFWRkZnJvb3RjYUBleGFtcGxlLm9yZzAeFw0xNDEyMTAyMTU4MThaFw0xNTEyMTAyMTU4MThaMIGDMQswCQYDVQQGEwJVUzELMAkGA1UECAwCQVoxETAPBgNVBAcMCEdvb2R5ZWFyMQwwCgYDVQQKDANEREYxDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJbG9jYWxob3N0MSQwIgYJKoZIhvcNAQkBFhVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMeCyNZbCTZphHQfB5g8FrgBq1RYzV7ikVw/pVGkz8gx3l3A99s8WtA4mRAeb6n0vTR9yNBOekW4nYOiEOq//YTi/frI1kz0QbEH1s2cI5nFButabD3PYGxUSuapbc+AS7+Pklr0TDI4MRzPPkkTp4wlORQ/a6CfVsNr/mVgL2CfAgMBAAGjgZkwgZYwCQYDVR0TBAIwADAnBglghkgBhvhCAQ0EGhYYRk9SIFRFU1RJTkcgUFVSUE9TRSBPTkxZMB0GA1UdDgQWBBSA95QIMyBAHRsd0R4s7C3BreFrsDAfBgNVHSMEGDAWgBThVMeX3wrCv6lfeF47CyvkSBe9xjAgBgNVHREEGTAXgRVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwDQYJKoZIhvcNAQEFBQADgYEAtRUp7fAxU/E6JD2Kj/+CTWqu8Elx13S0TxoIqv3gMoBW0ehyzEKjJi0bb1gUxO7n1SmOESp5sE3jGTnh0GtYV0D219z/09n90cd/imAEhknJlayyd0SjpnaL9JUd8uYxJexy8TJ2sMhsGAZ6EMTZCfT9m07XduxjsmDz0hlSGV0=
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:8993/logout"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8993/logout"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:8993/services/saml/sso"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8993/services/saml/sso"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>
To use the SAML IdP for authentication,
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select Web Context Policy Manager.
-
Under Authentication Types, set the authentication type to SAML for context paths as necessary. For example:
-
/search=SAML
-
Other authentication types can also be used in conjunction with the SAML type.
For example, if you wanted to secure the entire system with the IdP, but still allow legacy clients that don’t understand the SAML ECP specification to connect, you could set /=SAML|PKI
.
With that configuration, any clients that failed to connect using either the SAML 2.0 Web SSO Profile or the SAML ECP specification would fall back to 2-way TLS for authentication.
To configure the IdP client (also known as the SP) that interacts with the specified IdP,
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select IdP Client.
-
Populate IdP Metadata field through one of the following:
-
an HTTPS URL (https://) e.g., https://localhost:8993/services/idp/login/metadata,
-
a file URL (file:), or
-
an XML block to refer to desired metadata.
-
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://localhost:8993/services/idp/login">
<md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIIDEzCCAnygAwIBAgIJAIzc4FYrIp9mMA0GCSqGSIb3DQEBBQUAMHcxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJBWjEMMAoGA1UECgwDRERGMQwwCgYDVQQLDANEZXYxGTAXBgNVBAMMEERERiBEZW1vIFJvb3QgQ0ExJDAiBgkqhkiG9w0BCQEWFWRkZnJvb3RjYUBleGFtcGxlLm9yZzAeFw0xNDEyMTAyMTU4MThaFw0xNTEyMTAyMTU4MThaMIGDMQswCQYDVQQGEwJVUzELMAkGA1UECAwCQVoxETAPBgNVBAcMCEdvb2R5ZWFyMQwwCgYDVQQKDANEREYxDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJbG9jYWxob3N0MSQwIgYJKoZIhvcNAQkBFhVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMeCyNZbCTZphHQfB5g8FrgBq1RYzV7ikVw/pVGkz8gx3l3A99s8WtA4mRAeb6n0vTR9yNBOekW4nYOiEOq//YTi/frI1kz0QbEH1s2cI5nFButabD3PYGxUSuapbc+AS7+Pklr0TDI4MRzPPkkTp4wlORQ/a6CfVsNr/mVgL2CfAgMBAAGjgZkwgZYwCQYDVR0TBAIwADAnBglghkgBhvhCAQ0EGhYYRk9SIFRFU1RJTkcgUFVSUE9TRSBPTkxZMB0GA1UdDgQWBBSA95QIMyBAHRsd0R4s7C3BreFrsDAfBgNVHSMEGDAWgBThVMeX3wrCv6lfeF47CyvkSBe9xjAgBgNVHREEGTAXgRVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwDQYJKoZIhvcNAQEFBQADgYEAtRUp7fAxU/E6JD2Kj/+CTWqu8Elx13S0TxoIqv3gMoBW0ehyzEKjJi0bb1gUxO7n1SmOESp5sE3jGTnh0GtYV0D219z/09n90cd/imAEhknJlayyd0SjpnaL9JUd8uYxJexy8TJ2sMhsGAZ6EMTZCfT9m07XduxjsmDz0hlSGV0=
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor use="encryption">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIIDEzCCAnygAwIBAgIJAIzc4FYrIp9mMA0GCSqGSIb3DQEBBQUAMHcxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJBWjEMMAoGA1UECgwDRERGMQwwCgYDVQQLDANEZXYxGTAXBgNVBAMMEERERiBEZW1vIFJvb3QgQ0ExJDAiBgkqhkiG9w0BCQEWFWRkZnJvb3RjYUBleGFtcGxlLm9yZzAeFw0xNDEyMTAyMTU4MThaFw0xNTEyMTAyMTU4MThaMIGDMQswCQYDVQQGEwJVUzELMAkGA1UECAwCQVoxETAPBgNVBAcMCEdvb2R5ZWFyMQwwCgYDVQQKDANEREYxDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJbG9jYWxob3N0MSQwIgYJKoZIhvcNAQkBFhVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMeCyNZbCTZphHQfB5g8FrgBq1RYzV7ikVw/pVGkz8gx3l3A99s8WtA4mRAeb6n0vTR9yNBOekW4nYOiEOq//YTi/frI1kz0QbEH1s2cI5nFButabD3PYGxUSuapbc+AS7+Pklr0TDI4MRzPPkkTp4wlORQ/a6CfVsNr/mVgL2CfAgMBAAGjgZkwgZYwCQYDVR0TBAIwADAnBglghkgBhvhCAQ0EGhYYRk9SIFRFU1RJTkcgUFVSUE9TRSBPTkxZMB0GA1UdDgQWBBSA95QIMyBAHRsd0R4s7C3BreFrsDAfBgNVHSMEGDAWgBThVMeX3wrCv6lfeF47CyvkSBe9xjAgBgNVHREEGTAXgRVsb2NhbGhvc3RAZXhhbXBsZS5vcmcwDQYJKoZIhvcNAQEFBQADgYEAtRUp7fAxU/E6JD2Kj/+CTWqu8Elx13S0TxoIqv3gMoBW0ehyzEKjJi0bb1gUxO7n1SmOESp5sE3jGTnh0GtYV0D219z/09n90cd/imAEhknJlayyd0SjpnaL9JUd8uYxJexy8TJ2sMhsGAZ6EMTZCfT9m07XduxjsmDz0hlSGV0=
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:8993/logout"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8993/logout"/>
<md:NameIDFormat>
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
</md:NameIDFormat>
<md:NameIDFormat>
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
</md:NameIDFormat>
<md:NameIDFormat>
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:8993/services/idp/login"/>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8993/services/idp/login"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>
When using the included IdP, DDF can be configured to use the included Security Token Service(STS).
7.4.2.1.1. Configuring Included STS
An LDAP server can be used to maintain a list of DDF users and the attributes associated with them. The Security Token Service (STS) can use an LDAP server as an attribute store and convert those attributes to SAML claims.
DDF includes a demo LDAP server, but an external LDAP is required for actual installation.
The STS is installed by default in DDF.
-
Verify that the
serverKeystores.jks
file in<DDF_HOME>/etc/keystores
trusts the hostnames used in your environment (the hostnames of LDAP, and any DDF users that make use of this STS server). -
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Start the
security-sts-ldaplogin
andsecurity-sts-ldapclaimshandler
features. -
Select the Configuration tab.
-
Select the Security STS LDAP Login configuration.
-
Verify that the LDAP URL, LDAP Bind User DN, and LDAP Bind User Password fields match your LDAP server’s information.
-
The default DDF LDAP settings will match up with the default settings of the OpenDJ embedded LDAP server. Change these values to map to the location and settings of the LDAP server being used.
-
-
Select the Save changes button if changes were made.
-
Open the Security STS LDAP and Roles Claims Handler configuration.
-
Populate the same URL, user, and password fields with your LDAP server information.
-
Select the Save Changes button.
Configure the DDF to use this authentication scheme.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Open the Web Context Policy Manager configuration.
-
Under Authentication Types, make any desired authentication changes to contexts.
-
In order to use the SAML 2.0 Web SSO profile against a context, you must specify only the SAML authentication type.
-
-
Configure the client connecting to the STS.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Open the Security STS Client configuration.
-
Verify that the host/port information in the STS Address field points to your STS server. If you are using the default bundled STS, this information will already be correct.
See Security STS Client table for all configuration options.
The DDF should now use the SSO/STS/LDAP servers when it attempts to authenticate a user upon an attempted log in.
Connect to the server hosting the STS.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Security STS Server configuration.
-
Verify the hostname and usernames are correct.
See Security STS Server table for all configuration options.
Set up alternatives to displaying the username of the logged in user.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the SAML NameID Policy configuration.
-
Add any desired attributes to display instead of the username. (The first matching attribute will be used.)
-
Required Step for Security Hardening
-
Open the
<DDF_HOME>/etc/custom.system.properties
file. -
Edit the line
ws-security.subject.cert.constraints = .*CN=<MY_HOST_CN>.*
.-
By default this will only allow your hostname. To allow other desired hosts add their CNs to the regular expression within parentheses delimited by
|
:-
ws-security.subject.cert.constraints = .*CN=(<MY_HOST_CN>|<OTHER_HOST_CN>|<ANOTHER_HOST_CN>).*
-
-
To use OpenID Connect (OIDC) and OAuth 2.0, DDF needs to be connected to an external Identity Provider (IdP) which supports these protocols.
OIDC is used to authenticate (or log in) a user. To use this protocol in DDF, DDF needs the external IdP’s information.
To connect to an external IdP,
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select OIDC Handler Configuration.
-
Populate the fields with the external IdP’s information. For more detail, see the
OIDC Handler Configuration
section under Configure Single Sign On.
Once connected, the Web Context Policy Manager needs to be updated. to do so,
-
Under the Configuration tab in the Security application
-
Select the Web Context Policy Manager.
-
Under
Authentication Types
, add the context type of the endpoint you wish to protect with OIDC. For example/search=OIDC
.
OAuth 2.0 is an authorization protocol and DDF can use it when federating.
When a user queries a source that is configured to use this protocol, DDF will forward the user’s information (access token) with the request.
If a source can be configured to use OAuth 2.0, OAuth 2.0
will appear as an option under Authentication Type
in the source’s configuration.
To configure a source to use OAuth 2.0, under the source’s configuration,
-
Change the
Authentication Type
toOAuth 2.0
. -
Set the
OAuth Discovery Url
to the discovery URL where the OAuth provider’s metadata is hosted. -
Set the
OAuth Client ID
to the ID given to DDF when it was registered with the OAuth provider`. -
Set the
OAuth Client Secret
to the secret given to DDF when it was registered with the OAuth provider`. -
Set the
OAuth Flow
to the OAuth 2.0 flow to use when federating.
Note
|
If the system DDF is federating with is a DDF, the DDF receiving the federated request should be connected to an external IdP and have |
7.4.2.2. Connecting to an External Identity Provider
To connect to an external Identity Provider,
-
Provide the external IdP with DDF’s Service Provider (SP) metadata. The SP metadata can found at
https://<FQDN>:<PORT>/services/saml/sso/metadata
. -
Replace the IdP metadata field in DDF.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select IdP Client.
-
Populate the IdP Metadata field with the external IdP’s metadata.
-
Note
|
The certificate that the external IdP uses for signing will need to be added to the DDF’s keystore. See Updating Key Store / Trust Store via the Admin Console for details. |
Note
|
DDF may not interoperate successfully with all IdPs. To idenify the ones it can interoperate with use the The Security Assertion Markup Language (SAML) Conformance Test Kit (CTK) |
It is not recommended to remove or replace the included Service Provider. To add an additional, external Service Provider, add the SP metadata to the IdP Server configuration. See Configuring Security IdP Service Provider for more detail.
7.4.2.3. Configuring Without an Identity Provider
To configure DDF to not use an Identity Provider (IdP),
-
Disable the IdP feature.
-
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Uninstall the
security-idp
feature.
-
-
Change the Authentication Type if it is IdP.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select Web Context Policy Manager
-
Under Authentication Types, remove the SAML authentication type from all context paths.
-
7.4.2.3.1. Using STS without IdP
To configure DDF to use the included Security Token Service (STS) without an IdP, follow the same Configuring STS steps, with one additional configuration to make via the Web Context Policy Manager.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select Configuration.
-
Select the Web Context Policy Manager.
-
Add any needed authentication types to the Authentication Types list, such as
PKI
,BASIC
, etc.
7.4.2.4. Configuring Multi Factor Authentication
Mutli-factor authentication, sometimes referred to as two-factor authentication, allows for greater security. It does this by requiring users to provide multiple proofs of identity, typically through something they know (such as a password), and something they have/are (such as a randomly generated pin number sent to one of their personal devices). The IdP that comes with DDF does not support multi-factor authentication by default.
Keycloak can be used to help setup and configure multi-factor authentication. See Connecting to an External Identity Provider on how to initially hookup Keycloak.
-
Download and install Keycloak from here: Keycloak Downloads {external link}
-
See Choosing an Operating Mode {external link} to choose a specific operation mode.
-
Set up an Admin User following these steps here: Server Admin Initialization {external link}
-
Refer to OTP Policies {external link} for how to set up multi-factor authentication using supported authentication tools such as FreeOTP and Google Authenticator.
See the Keycloak Documentation {external link} for more information and details about how to configure Keycloack for multi-factor authentication.
7.4.3. Configuring SOAP Services for Users
If using SOAP services, DDF can be configured to use the included Security Token Service (STS).
7.4.3.1. Connecting to Included STS with SOAP
DDF includes a STS implementation that can be used for user authentication over SOAP services.
Configure the STS WSS.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select Configuration.
-
Select Security STS WSS.
-
Update the Claims that should be requested by the STS.
7.4.4. Connecting to an LDAP Server
Warning
|
The configurations for Security STS LDAP and Roles Claims Handler and Security STS LDAP Login contain plain text default passwords for the embedded LDAP, which is insecure to use in production. |
Use the Encryption Service, from the Command Console to set passwords for your LDAP server. Then change the LDAP Bind User Password in the Security STS LDAP and Roles Claims Handler configurations to use the encrypted password.
A claim is an additional piece of data about a principal that can be included in a token along with basic token data. A claims manager provides hooks for a developer to plug in claims handlers to ensure that the STS includes the specified claims in the issued token.
Claims handlers convert incoming user credentials into a set of attribute claims that will be populated in the SAML assertion.
For example, the LDAPClaimsHandler
takes in the user’s credentials and retrieves the user’s attributes from a backend LDAP server.
These attributes are then mapped and added to the SAML assertion being created.
Integrators and developers can add more claims handlers that can handle other types of external services that store user attributes.
See the Security STS LDAP and Roles Claims Handler for all possible configurations.
7.4.5. Updating System Users
By default, all system users are located in the <DDF_HOME>/etc/users.properties
and <DDF_HOME>/etc/users.attributes
files.
The default users included in these two files are "admin" and "localhost".
The users.properties
file contains username, password, and role information; while the users.attributes
file is used to mix in additional attributes.
The users.properties
file must also contain the user corresponding to the fully qualified domain name (FQDN) of the system where DDF is running.
This FQDN user represents this host system internally when making decisions about what operations the system is capable of performing.
For example, when performing a DDF Catalog Ingest, the system’s attributes will be checked against any security attributes present on the metacard, prior to ingest, to determine whether or not the system should be allowed to ingest that metacard.
Additionally, the users.attributes
file can contain user entries in a regex format.
This allows an administrator to mix in attributes for external systems that match a particular regex pattern.
The FQDN user within the users.attributes
file should be filled out with attributes sufficient to allow the system to ingest the expected data.
The users.attributes
file uses a JSON format as shown below:
1
2
3
4
5
6
7
8
9
10
11
12
{
"admin" : {
"test" : "testValue",
"test1" : [ "testing1", "testing2", "testing3" ]
},
"localhost" : {
},
".*host.*" : {
"reg" : "ex"
}
}
For this example, the "admin" user will end up with two additional claims of "test" and "test1" with values of "testValue" and [ "testing1", "testing2", "testing3" ] respectively. Also, any host matching the regex ".host." would end up with the claim "reg" with the single value of "ex". The "localhost" user would have no additional attributes mixed in.
Warning
|
It is possible for a regex in |
Warning
|
If your data will contain security markings, and these markings are being parsed out into the metacard security attributes via a PolicyPlugin, then the FQDN user MUST be updated with attributes that would grant the privileges to ingest that data. Failure to update the FQDN user with sufficient attributes will result in an error being returned for any ingest request. |
Warning
|
The following attribute values are not allowed:
Additionally, attribute names should not be repeated, and the order that the attributes are defined and the order of values within an array will be ignored. |
7.4.6. Restricting Access to Admin Console
-
Required Step for Security Hardening
If you have integrated DDF with your existing security infrastructure, then you may want to limit access to parts of the DDF based on user roles/groups.
Limit access to the Admin Console to those users who need access. To set access restrictions on the Admin Console, consult the organization’s security architecture to identify specific realms, authentication methods, and roles required.
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select the Web Context Policy Manager.
-
A dialogue will pop up that allows you to edit DDF access restrictions.
-
Once you have configured your realms in your security infrastructure, you can associate them with DDF contexts.
-
If your infrastructure supports multiple authentication methods, they may be specified on a per-context basis.
-
Role requirements may be enforced by configuring the required attributes for a given context.
-
The white listed contexts allows child contexts to be excluded from the authentication constraints of their parents.
-
7.4.6.1. Restricting Feature, App, Service, and Configuration Access
-
Required Step for Security Hardening
Limit access to the individual applications, features, or services to those users who need access. Organizational requirements should dictate which applications are restricted and the extent to which they are restricted.
-
Navigate to the Admin Console.
-
Select the Admin application.
-
Select the Configuration tab.
-
Select the Admin Configuration Policy.
-
To add a feature or app permission:
-
Add a new field to "Feature and App Permissions" in the format of:
<feature name>/<app name> = "attribute name=attribute value","attribute name2=attribute value2", …
-
For example, to restrict access of any user without an admin role to the catalog-app:
catalog-app = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role=admin", …
-
-
To add a configuration permission:
-
Add a new field to "Configuration Permissions" in the format of:
configuration id = "attribute name=attribute value","attribute name2=attribute value2", …
-
For example, to restrict access of any user without an admin role to the Web Context Policy Manager:
org.codice.ddf.security.policy.context.impl.PolicyManager="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role=admin"
-
If a permission is specified, any user without the required attributes will be unable to see or modify the feature, app, or configuration.
7.4.7. Removing Default Users
-
Required Step for Security Hardening
The default security configuration uses a property file located at <DDF_HOME>/etc/users.properties
to store users and passwords.
A hardened system will remove this file and manage all users externally, via an LDAP server or by other means.
Note
|
Default Users are an Insecure Default
The Admin Console has an insecure default warning if the default users are not removed. |
Once DDF is configured to use an external user (such as LDAP), remove the users.properties
file from the <DDF_HOME>/etc
directory.
Use of a users.properties
file should be limited to emergency recovery operations and replaced as soon as effectively possible.
The deletion of the default users in the users.properties
file can be done automatically after 72 hours.
This feature can be found at Admin Console → Admin → Default Users Deletion Scheduler → Enable default users automatic deletion.
Warning
|
Once the default users are removed, the |
Note
|
Emergency Use of
users.properties fileTypically, the DDF does not manage passwords.
Authenticators are stored in an external identity management solution. However, administrators may temporarily use a If a system recovery account is configured in
|
Note
|
Compliance Reviews
It is recommended to perform yearly reviews of accounts for compliance with organizational account management requirements. |
7.4.8. Disallowing Login Without Certificates
DDF can be configured to prevent login without a valid PKI certificate.
-
Navigate to the Admin Console.
-
Select Security.
-
Select Web Context Policy Manager.
-
Add a policy for each context requiring restriction.
-
For example:
/search=PKI
will disallow login without certificates to the Search UI. -
The format for the policy should be:
/<CONTEXT>=PKI
-
-
Click Save.
Note
|
Ensure certificates comply with organizational hardening policies. |
7.4.9. Managing Certificate Revocation
-
Required Step for Security Hardening
For hardening purposes, it is recommended to implement a way to verify a Certificate Revocation List (CRL) at least daily or an Online Certificate Status Protocol (OCSP) server.
7.4.9.1. Managing a Certificate Revocation List (CRL)
A Certificate Revocation List is a collection of formerly-valid certificates that should explicitly not be accepted.
7.4.9.1.1. Creating a CRL
Create a CRL in which the token issuer’s certificate is valid. The example uses OpenSSL.
$> openssl ca -gencrl -out crl-tokenissuer-valid.pem
Note
|
Windows and OpenSSL
Windows does not include OpenSSL by default. For Windows platforms, a additional download of OpenSSL or an alternative is required. |
$> openssl ca -revoke tokenissuer.crt $> openssl ca -gencrl -out crl-tokenissuer-revoked.pem
-
Use the following command to view the serial numbers of the revoked certificates:
$> openssl crl -inform PEM -text -noout -in crl-tokenissuer-revoked.pem
7.4.9.1.2. Enabling Certificate Revocation
Note
|
Enabling CRL revocation or modifying the CRL file will require a restart of DDF to apply updates. |
-
Place the CRL in <DDF_HOME>/etc/keystores.
-
Add the line
org.apache.ws.security.crypto.merlin.x509crl.file=etc/keystores/<CRL_FILENAME>
to the following files (Replace<CRL_FILENAME>
with the URL or file path of the CRL location):-
<DDF_HOME>/etc/ws-security/server/encryption.properties
-
<DDF_HOME>/etc/ws-security/issuer/encryption.properties
-
<DDF_HOME>/etc/ws-security/server/signature.properties
-
<DDF_HOME>/etc/ws-security/issuer/signature.properties
-
-
(Replace <CRL_FILENAME> with the file path or URL of the CRL file used in previous step.)
Adding this property will also enable CRL revocation for any context policy implementing PKI authentication.
For example, adding an authentication policy in the Web Context Policy Manager of /search=PKI
will disable basic authentication and require a certificate for the search UI.
If a certificate is not in the CRL, it will be allowed through, otherwise it will get a 401 error.
If no certificate is provided, and guest access is enabled on the web context policy, guest access will be granted.
This also enables CRL revocation for the STS endpoint.
The STS CRL Interceptor monitors the same encryption.properties
file and operates in an identical manner to the PKI Authenication’s CRL handler. Enabling the CRL via the encryption.properties
file will also enable it for the STS, and also requires a restart.
If the CRL cannot be placed in <DDF_HOME>/etc/keystores but can be accessed via an HTTPS URL:
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select Certificate Revocation List (CRL)
-
Add the HTTPS URL under CRL URL address
-
Check the Enable CRL via URL option
A local CRL file will be created and the encryption.properties
and signature.properties
files will be set as mentioned above.
The PKIHandler implements CRL revocation, so any web context that is configured to use PKI authentication will also use CRL revocation if revocation is enabled.
-
After enabling revocation (see above), open the Web Context Policy Manager.
-
Add or modify a Web Context to use PKI in authentication. For example, enabling CRL for the search ui endpoint would require adding an authorization policy of
/search=PKI
-
If guest access is also required, check the 'Allow Guest Access` box in the policy.
With guest access, a user with a revoked certificate will be given a 401 error, but users without a certificate will be able to access the web context as the guest user.
The STS CRL interceptor does not need a web context specified.
The CRL interceptor for the STS will become active after specifying the CRL file path, or the URL for the CRL, in the encryption.properties
file and restarting DDF.
Note
|
Disabling or enabling CRL revocation or modifying the CRL file will require a restart of DDF to apply updates. If CRL checking is already enabled, adding a new context via the Web Context Policy Manager will not require a restart. |
Note
|
This section explains how to add CXF’s CRL revocation method to an endpoint and not the CRL revocation method in the |
This guide assumes that the endpoint being created uses CXF and is being started via Blueprint from inside the OSGi container. If other tools are being used the configuration may differ.
Add the following property to the jasws
endpoint in the endpoint’s blueprint.xml
:
<entry key="ws-security.enableRevocation" value="true"/>
jaxws:endpoint
with the property:<jaxws:endpoint id="Test" implementor="#testImpl"
wsdlLocation="classpath:META-INF/wsdl/TestService.wsdl"
address="/TestService">
<jaxws:properties>
<entry key="ws-security.enableRevocation" value="true"/>
</jaxws:properties>
</jaxws:endpoint>
A Warning similar to the following will be displayed in the logs of the source and endpoint showing the exception encountered during certificate validation:
11:48:00,016 | WARN | tp2085517656-302 | WSS4JInInterceptor | ecurity.wss4j.WSS4JInInterceptor 330 | 164 - org.apache.cxf.cxf-rt-ws-security - 2.7.3 |
org.apache.ws.security.WSSecurityException: General security error (Error during certificate path validation: Certificate has been revoked, reason: unspecified)
at org.apache.ws.security.components.crypto.Merlin.verifyTrust(Merlin.java:838)[161:org.apache.ws.security.wss4j:1.6.9]
at org.apache.ws.security.validate.SignatureTrustValidator.verifyTrustInCert(SignatureTrustValidator.java:213)[161:org.apache.ws.security.wss4j:1.6.9]
[ ... section removed for space]
Caused by: java.security.cert.CertPathValidatorException: Certificate has been revoked, reason: unspecified
at sun.security.provider.certpath.PKIXMasterCertPathValidator.validate(PKIXMasterCertPathValidator.java:139)[:1.6.0_33]
at sun.security.provider.certpath.PKIXCertPathValidator.doValidate(PKIXCertPathValidator.java:330)[:1.6.0_33]
at sun.security.provider.certpath.PKIXCertPathValidator.engineValidate(PKIXCertPathValidator.java:178)[:1.6.0_33]
at java.security.cert.CertPathValidator.validate(CertPathValidator.java:250)[:1.6.0_33]
at org.apache.ws.security.components.crypto.Merlin.verifyTrust(Merlin.java:814)[161:org.apache.ws.security.wss4j:1.6.9]
... 45 more
7.4.9.2. Managing an Online Certificate Status Protocol (OCSP) Server
An Online Certificate Status Protocol is a protocol used to verify the revocation status of a certificate. An OCSP server can be queried with a certificate to verify if it is revoked.
The advantage of using an OCSP Server over a CRL is the fact that a local copy of the revoked certificates is not needed.
7.4.9.2.1. Enabling OCSP Revocation
-
Navigate to the Admin Console.
-
Select the Security application.
-
Select the Configuration tab.
-
Select Online Certificate Status Protocol (OCSP)
-
Add the URL of the OCSP server under OCSP server URL.
-
Check the Enable validating a certificate against an OCSP server option.
Note
|
If an error occurs while communicating with the OCSP server, an alert will be posted to the Admin Console. Until the error is resolved, certificates will not be verified against the server. |
7.5. Configuring Data Management
Data ingested into DDF has security attributes that can be mapped to users' permissions to ensure proper access. This section covers configurations that ensure only the appropriate data is contained in or exposed by DDF.
7.5.1. Configuring Solr
The default catalog provider for DDF is Solr. If using another catalog provider, see Changing Catalog Providers.
7.5.1.1. Configuring Solr Catalog Provider Synonyms
When configured, text searches in Solr will utilize synonyms when attempting to match text within the catalog.
Synonyms are used during keyword/anyText searches as well as when searching on specific text attributes when using the like
/ contains
operator.
Text searches using the equality
/ exact match
operator will not utilize synonyms.
Solr utilizes a synonyms.txt
file which exists for each Solr core.
Synonym matching is most pertinent to metacards which are contained within 2 cores: catalog
and metacard_cache
.
7.5.1.1.1. Defining synonym rules in the Solr Provider
-
Edit the
synonyms.txt
file under thecatalog
core. For each synonym group you want to define, add a line with the synonyms separated by a comma. For example:
United States, United States of America, the States, US, U.S., USA, U.S.A
-
Save the file
-
Repeat the above steps for the
metacard_cache
core. -
Restart the DDF.
Note
|
Data does not have to be re-indexed for the synonyms to take effect. |
7.5.1.2. Hardening Solr
The following sections provide hardening guidance for Solr; however, they are provided only as reference and additional security requirements may be added.
7.5.1.2.1. Hardening Solr Server Configuration
The Solr server configuration is configured to be secure by default. No additional hardening should be necessary. The default configuration starts Solr with TLS enabled and basic authentication required. That means DDF must trust Solr’s PKI certificate.
7.5.1.2.2. Solr Server Password Management
By default, DDF is configured to use Solr server. To verify this, view the property
solr.client
. If the property is set to HttpSolrClient
,
DDF is configured to use Solr server.
To ensure the security of its communication with Solr server, DDF sends HTTP requests over TLS. Solr is configured to use basic authentication to further ensure the requests originated from DDF. There are several system properties that control basic authentication and password management.
-
solr.useBasicAuth
Send basic authentication header if property istrue
-
solr.username
Username for basic authentication with Solr server. -
solr.password
Password for basic authentication. -
solr.attemptAutoPasswordChange
If this property istrue
, DDF attempts to change the default password to a randomly generated secure password if it detects the default password is in use. The new password is encrypted and then stored in the system properties.
The Solr distrubition included with DDF comes already configured with a user. To see the
username or default password, either inspect the file
<DDF_HOME>/etc/custom.system.properties
or refer to the properties
here.
A limitation of the current implementation is that the Solr password is not recoverable. Further, the migration command does not currently migrate the password. It may be necessary to reset the password:
-
After a migration.
-
If the administator needs access to the Solr admin UI.
-
If the administator wants to use their own password.
-
To prevent DDF from attempting to change the password set the property
solr.attemptAutoPasswordChange
tofalse
in the file<DDF_HOME>/etc/custom.system.properties
Note
|
If DDF has generated an encrypted password, the password must be reset before proceeding. Follow the procedure in Restore the Default Password in Solr before proceeding. |
-
To change the Solr password to a specific string, send Solr an HTTP POST request. This is covered in the official Solr documentation . Here is an example that uses the command line utility
curl
to change the password fromadmin
tonewpassword
:curl -k -u "admin:admin" "https://{FQDN}:{PORT}/solr/admin/authentication" -H 'Content-type:application/json' -d "{ 'set-user': {'admin' : 'newpassword'}}"
-
Encrypt the password using the Encryption Service. The encryption command enciphers the password. It is safe to save the peristed password in a file.
-
Update property
solr.password
in the file <DDF_HOME>/etc/custom.system.properties` to be the ouput from the encryption command. Be sure to includeENC(
and)
characters produced by the encryption comand. Note that the default password is not enclosed inENC()
because that is not necessary for cleartext. Cleartext is used by the system exactly as it appears. follow these instructions. -
Finally, restart DDF
-
Restore the
<DDF_HOME>/solr/server/solr/security.json
from a zip file of the DDF distribution.
OR
-
Edit the
<DDF_HOME>/solr/server/solr/security.json
file. Solr stores a salted hash of the user passwords in this file. -
Assuming the Solr username is
admin
, change the credentials section to match this string:"credentials": { "admin": "EjjOS/zyQ1KQQdSXFb/rFm7w6MItU5pmdthM35ZiJaA= ZZI7d4jf/8hz5oZz7ljBE6+uv1wqncj+VudX3arbib4="}
The quoted string following the username
admin
is the salted hash for the passwordadmin
. -
Edit the file
<DDF_HOME>/etc/custom.system.properties
and change the value ofsolr.password
toadmin
. -
Optional: Prevent DDF from automatically changing the Solr password.
To disable Solr’s basic authentication mechanism, rename or remove the file
<DDF_HOME>/solr/server/solr/security.json
and restart Solr. The file security.json
configures Solr to use basic authetnication and defines Solr users. If the file is not present,
Solr requires no login. This could a security issue in many environments and it is recommended
to never disable Solr authentication in an operational environment. If authentication is disabled,
the system property solr.useBasicAuth
may be set to
false
.
7.5.1.2.3. Configuring Solr Encryption
While it is possible to encrypt the Solr index, it decreases performance significantly. An encrypted Solr index also can only perform exact match queries, not relative or contextual queries. As this drastically reduces the usefulness of the index, this configuration is not recommended. The recommended approach is to encrypt the entire drive through the Operating System of the server on which the index is located.
7.5.1.3. Accessing the Solr Admin UI
The Solr Admin UI for Solr server configurations can be accessed from a web browser with a username and password.
7.5.1.3.1. Solr Admin UI’s URL
The Solr server’s URL is configured in DDF’s custom.system.properties
file. See
solr.http.url for more information.
An example of a typical URL for the Solr Admin UI is https://hostname:8994
.
7.5.1.3.2. Solr Admin UI’s Username and Password
The Solr admin username is configured in the custom.system.properties
file. See
solr.username. The password is also stored in the
custom.system.properties
file, but the password is encrypted and not recoverable. See
Solr Server Password Management.
7.5.2. Changing Catalog Providers
This scenario describes how to reconfigure DDF to use a different catalog provider.
This scenario assumes DDF is already running.
-
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Find and Stop the installed Catalog Provider
-
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Find and Start the desired Catalog Provider.
7.5.3. Changing Hostname
By default, the STS server, STS client and the rest of the services use the system property org.codice.ddf.system.hostname
which is defaulted to 'localhost' and not to the fully qualified domain name of the DDF instance.
Assuming the DDF instance is providing these services, the configuration must be updated to use the fully qualified domain name as the service provider.
If the DDF is being accessed from behind a proxy or load balancer, set the system property org.codice.ddf.external.hostname
to the hostname users will be using to access the DDF.
This can be changed during Initial Configuration or later by editing the <DDF_HOME>/etc/custom.system.properties
file.
7.5.4. Configuring Errors and Warnings
DDF performs several types of validation on metadata ingested into the catalog. Depending on need, configure DDF to act on the warnings or errors discovered.
7.5.4.1. Enforcing Errors or Warnings
Prevent data with errors or warnings from being ingested at all.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select Configuration.
-
Select Metacard Validation Marker Plugin.
-
Enter ID of validator(s) to enforce.
-
Select Enforce errors to prevent ingest for errors.
-
Select Enforce warnings to prevent ingest for warnings.
7.5.4.2. Hiding Errors or Warnings from Queries
Prevent invalid metacards from being displayed in query results, unless specifically queried.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select Configuration.
-
Select Catalog Federation Strategy.
-
Deselect Show Validations Errors to hide metacards with errors.
-
Deselect Show Validations Warnings to hide metacards with warnings.
7.5.4.3. Hiding Errors and Warnings from Users Based on Role
-
Required Step for Security Hardening
Prevent certain users from seeing data with certain types of errors or warnings. Typically, this is used for security markings. If the Metacard Validation Filter Plugin is configured to Filter errors and/or Filter warnings, metacards with errors/warnings will be hidden from users without the specified user attributes.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select Configuration.
-
Select Metacard Validation Filter Plugin.
-
For Attribute map, enter both the metacard
SECURITY
attribute to filter and the user attribute to filter.-
The default attribute for viewing invalid metacards is
invalid-state
-
invalid-state=<USER ROLE>
. -
Replace
<USER ROLE>
with the roles that should be allowed to view invalid metacards.NoteTo harden the system and prevent other DDF systems from querying invalid data in the local catalog, it is recommended to create and set user roles that are unique to the local system (ie. a user role that includes a UUID).
-
-
-
Select Filter errors to filter errors. Users without the
invalid-state
attribute will not see metacards with errors. -
Select Filter warnings to filter warnings. Users without the
invalid-state
attribute will not see metacards with warnings.
7.5.5. Content Directory Monitor
The Content Directory Monitor (CDM) provides the capability to easily add content and metacards into the Catalog by placing a file in a directory.
7.5.5.1. Installing the Content Directory Monitor
The Content Directory Monitor is installed by default with a standard installation of the Catalog application.
7.5.5.2. Configuring Permissions for the Content Directory Monitor
Tip
|
If monitoring a WebDav server, then adding these permissions is not required and this section can be skipped. |
Configuring a Content Directory Monitor requires adding permissions to the Security Manager before CDM configuration.
Configuring a CDM requires adding read and write permissions to the directory being monitored. The following permissions, replacing <DIRECTORY_PATH> with the path of the directory being monitored, are required for each configured CDM and should be placed in the CDM section inside <DDF_HOME>/security/configurations.policy.
Warning
|
Adding New Permissions
After adding permissions, a system restart is required for them to take effect. |
-
permission java.io.FilePermission "<DIRECTORY_PATH>", "read";
-
permission java.io.FilePermission "<DIRECTORY_PATH>${/}-", "read, write";
Trailing slashes after <DIRECTORY_PATH> have no effect on the permissions granted. For example, adding a permission for "${/}test${/}path" and "${/}test${/}path${/}" are equivalent. The recursive forms "${/}test${/}path${/}-", and "${/}test${/}path${/}${/}-" are also equivalent.
Line 1 gives the CDM the permissions to read from the monitored directory path. Line 2 gives the CDM the permissions to recursively read and write from the monitored directory path, specified by the directory path’s suffix "${/}-".
If a CDM configuration is deleted, then the corresponding permissions that were added should be deleted to avoid granting unnecessary permissions to parts of the system.
7.5.5.3. Configuring the Content Directory Monitor
Important
|
Content Directory Monitor Permissions
When configuring a Content Directory Monitor, make sure to set permissions on the new directory to allow DDF to access it. Setting permissions should be done before configuring a CDM. Also, don’t forget to add permissions for products outside of the monitored directory. See Configuring Permissions for the Content Directory Monitor for in-depth instructions on configuring permissions. |
Note
|
If there’s a metacard that points to a resource outside of the CDM, then you must configure the URL Resource Reader to be able to download it. |
Warning
|
Monitoring Directories In Place
If monitoring a directory in place, then the URL Resource Reader must be configured prior to configuring the CDM to allow reading from the configured directory. This allows the Catalog to download the products. |
Configure the CDM from the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Configuration tab.
-
Select Catalog Content Directory Monitor.
See Content Directory Monitor configurations for all possible configurations.
7.5.5.4. Using the Content Directory Monitor
The CDM processes files in a directory, and all of its sub-directories. The CDM offers three options:
-
Delete
-
Move
-
Monitor in place
Regardless of the option, the DDF takes each file in a monitored directory structure and creates a metacard for it. The metacard is linked to the file. The behavior of each option is given below.
-
Copies the file into the Content Repository.
-
Creates a metacard in the Catalog from the file.
-
Erases the original file from the monitored directory.
-
Copies the file into the directory
.\ingested
(this will double the disk space used) -
Copies the file into the Content Repository.
-
Creates a metacard in the Catalog from the file.
-
Erases the original file from the monitored directory.
-
Creates a metacard in the Catalog from the file.
-
Creates a reference from the metacard to the original file in the monitored directory.
-
If the original file is deleted, the metacard is removed from the Catalog.
-
If the original file is modified, the metacard is updated to reflect the new content.
-
If the original file is renamed, the old metacard is deleted and a new metacard is created.
The CDM supports parallel processing of files (up to 8 files processed concurrently). This is configured by setting the number of Maximum Concurrent Files in the configuration. A maximum of 8 is imposed to protect system resources.
When the CDM is set up, the directory specified is continuously scanned, and files are locked for processing based on the ReadLock Time Interval. This does not apply to the Monitor in place processing directive. Files will not be ingested without having a ReadLock that has observed no change in the file size. This is done so that files that are in transit will not be ingested prematurely. The interval should be dependent on the speed of the copy to the directory monitor (ex. network drive vs local disk). For local files, the default value of 500 milliseconds is recommended. The recommended interval for network drives is 1000 - 2000 milliseconds. If the value provided is less than 100, 100 milliseconds will be used. It is also recommended that the ReadLock Time Interval be set to a lower amount of time when the Maximum Concurrent Files is set above 1 so that files are locked in a timely manner and processed as soon as possible. When a higher ReadLock Time Interval is set, the time it takes for files to be processed is increased.
The CDM supports setting metacard attributes directly when DDF ingests a file. Custom overrides are entered in the form:
attribute-name=attribute-value
For example, to set the contact email for all metacards, add the attribute override:
contact.point-of-contact-email=doctor@clinic.com
Each override sets the value of a single metacard attribute. To set the value of an additional attribute, select the "plus" icon in the UI. This creates an empty line for the entry.
To set multi-valued attributes, use a separate override for each value. For example, to add the keywords PPI and radiology to each metacard, add the custom attribute overrides:
topic.keyword=PPI
topic.keyword=radiology
Attributes will only be overridden if they are part of the metacard type or are injected.
All attributes in the catalog taxonomy tables are injected into all metacards by default and can be overridden.
Important
|
If an overridden attribute is not part of the metacard type or injected the attribute will not be added to the metacard. |
For example, if the metacard type contains contact email,
contact.point-of-contact-email
but the value is not currently set, adding an attribute override will set the attribute value. To override attributes that are not part of the metacard type, attribute injection can be used.
The CDM blacklist uses the "bad.files" and "bad.file.extensions" properties from the custom.system.properties file in "etc/" in order to prevent malicious or unwanted data from being ingested into DDF. While the CDM automatically omits hidden files, this is particularly useful when an operating system automatically generates files that should not be ingested. One such example of this is "thumbs.db" in Windows. This file type and any temporary files are included in the blacklist.
If the CDM fails to read the file, an error will be logged in the ingest log. If the directory monitor is
configured to Delete or Move, the original file is also moved to the \.errors
directory.
-
Multiple directories can be monitored. Each directory has an independent configuration.
-
To support the monitoring in place behavior, DDF indexes the files to track their names and modification timestamps. This enables the Content Directory Monitor to take appropriate action when files are changed or deleted.
-
The Content Directory Monitor recursively processes all subdirectories.
7.5.6. Configuring System Usage Message
The Platform UI configuration contains the settings for displaying messages to users at login or in banners in the headers and footers of all pages. For, example this configuration can provide warnings that system usage is monitored or controlled.
-
Navigate to the Admin Console.
-
Select the Platform application.
-
Select Configuration.
-
Select Platform UI Configuration.
-
Select Enable System Usage Message.
-
Enter text in the remaining fields and save.
See the Platform UI for all possible configurations.
7.5.7. Configuring Data Policy Plugins
Configure the data-related policy plugins to determine the accessibility of data held by DDF.
7.5.7.1. Configuring the Metacard Attribute Security Policy Plugin
The Metacard Attribute Security Policy Plugin combines existing metacard attributes to make new attributes and adds them to the metacard.
-
Navigate to the Admin Console.
-
Select the Catalog application tile
-
Select the Configuration tab
-
Select the Metacard Attribute Security Policy Plugin.
Sample configuration of the Metacard Attribute Security Policy Plugin.
To configure the plugin to combine the attributes sourceattribute1
and sourceattribute2
into a new
attribute destinationattribute1
using the union,
enter these two lines under the title Metacard Union Attributes
Metacard Union Attributes |
---|
|
|
See Metacard Attribute Security Policy Plugin configurations for all possible configurations.
7.5.7.2. Configuring the Metacard Validation Marker Plugin
By default, the Metacard Validation Marker Plugin will mark metacards with validation errors and warnings as they are reported by each metacard validator and then allow the ingest.
To prevent the ingest of certain invalid metacards, the Metacard Validity Marker
plugin can be configured to "enforce" one or more validators.
Metacards that are invalid according to an "enforced" validator will not be ingested.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Configuration tab.
-
Select the Metacard Validity Marker Plugin.
-
If desired, enter the ID of any metacard validator to enforce. This will prevent ingest of metacards that fail validation.
-
If desired, check Enforce Errors or Enforce Warnings, or both.
-
See Metacard Validity Marker Plugin configurations for all possible configurations.
7.5.7.3. Configuring the Metacard Validity Filter Plugin
The Metacard Validity Filter Plugin determines whether metacards with validation errors or warnings are filtered from query results.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Configuration tab.
-
Select the Metacard Validity Filter Plugin.
-
Check Filter Errors to hide metacards with errors from users.
-
Check Filter Warnings to hide metacards with warnings from users.
-
See Metacard Validity Filter Plugin configurations for all possible configurations.
7.5.7.4. Configuring the XML Attribute Security Policy Plugin
The XML Attribute Security Policy Plugin finds security attributes contained in a metacard’s metadata.
-
Navigate to the Admin Console.
-
Select the Catalog application tile.
-
Select the Configuration tab.
-
Select the XML Attribute Security Policy Plugin configuration.
See XML Attribute Security Policy Plugin configurations for all possible configurations.
7.5.8. Configuring Data Access Plugins
Configure access plugins to act upon the rules and attributes configured by the policy plugins and user attributes.
7.5.8.1. Configuring the Security Audit Plugin
The Security Audit Plugin audits specific metacard attributes.
To configure the Security Audit Plugin:
-
Navigate to the Admin Console.
-
Select Catalog application.
-
Select Configuration tab.
-
Select Security Audit Plugin.
Add the desired metacard attributes that will be audited when modified.
See Security Audit Plugin configurations for all possible configurations.
7.6. Configuring Security Policies
User attributes and Data attributes are matched by security policies defined within DDF.
7.6.1. Configuring the Web Context Policy Manager
The Web Context Policy Manager defines all security policies for REST endpoints within DDF. It defines:
-
the realms a context should authenticate against.
-
the type of authentication that a context requires.
-
any user attributes required for authorization.
See Web Context Policy Manager Configurations for detailed descriptions of all fields.
7.6.1.1. Guest Access
Guest access is a toggleable configuration. Enabling guest access will cause all users to be assigned a guest principal for use throughout the entire system. The guest principal will be used either by itself or along with any other principals acquired from configured authentication types.
7.6.1.2. Session Storage
Enabling session storage allows the system to persist the user login through the use of cookies.
Note that the SAML
and OIDC
authentication types require session storage to be enabled.
7.6.1.3. Authentication Types
As you add REST endpoints, you may need to add different types of authentication through the Web Context Policy Manager.
Any web context that allows or requires specific authentication types should be added here with the following format:
/<CONTEXT>=<AUTH_TYPE>|<AUTH_TYPE|...
Authentication Type | Description |
---|---|
|
Activates basic authentication. |
|
Activates public key infrastructure authentication. |
|
Activates single-sign on (SSO) across all REST endpoints that use SAML. |
|
Activates single-sign on (SSO) across all REST endpoints that use OIDC. |
7.6.1.3.1. Terminating and Non-Terminating Authentication Types
Terminating authentication types are authentication types where, once hit, must either allow or forbid access to the system. No other authentication types will be checked once a terminating authentication type is hit.
Non-Terminating authentication types are authentication types where, once hit, must first verify that the client supports the authentication type’s method of obtaining credentials. If the client supports the non-terminating authentication type’s method of obtaining credentials, it either allows or forbids access to the system. However if the client does not support the non-terminating authentication type’s method of obtaining credentials, the system will continue to the next configured authentication type.
BASIC
is the only terminating authentication type.
Every other authentication type is non-terminating.
For example: assume a context is protected by the non-terminating SAML
authorization type.
The system first checks to see if the client supports the acquisition of SAML credentials.
-
If the connecting client is a browser, the system can acquire SAML credentials.
-
If the connecting client is a machine that supports SAML ECP, the system can acquire SAML credentials.
-
If the connecting client is a machine that does not support SAML ECP, the system cannot acquire SAML credentials.
If the system can acquire SAML credentials from the client, the system will attempt to acquire said credentials and either allow or forbid access. If the system cannot acquire SAML credentials from the client, the system will continue to the next configured authentication type.
Contrarily, assume a context is protected by the terminating BASIC
authentication type.
Once this authentication type is hit, the system either allows or forbids access to the system, without checking if the client supports the acquisition of BASIC credentials.
7.6.1.4. Required Attributes
The fields for required attributes allows configuring certain contexts to only be accessible to users with pre-defined attributes.
For example, the default required attribute for the /admin
context is role=system-admin
, limiting access to the Admin Console to system administrators
7.6.1.5. White Listed Contexts
White listed contexts are trusted contexts which will bypass security. Any sub-contexts of a white listed context will be white listed as well, unless they are specifically assigned a policy.
7.6.2. Configuring Catalog Filtering Policies
Filtering is the process of evaluating security markings on data products, comparing them to the users permissions and protecting resources from inappropriate access.
There are two options for processing filtering policies: internally, or through the use of a policy formatted in eXtensible Access Control Markup Language (XACML). The procedure for setting up a policy differs depending on whether that policy is to be used internally or by the external XACML processing engine.
7.6.2.1. Setting Internal Policies
-
Navigate to the Admin Console.
-
Select the Security application.
-
Click the Configuration tab.
-
Click on the Security AuthZ Realm configuration.
-
Add any attribute mappings necessary to map between subject attributes and the attributes to be asserted.
-
For example, the above example would require two Match All mappings of
subjectAttribute1=assertedAttribute1
andsubjectAttribute2=assertedAttribute2`
-
Match One mappings would contain
subjectAttribute3=assertedAttribute3
andsubjectAttribute4=assertedAttribute4
.
-
With the security-pdp-authz
feature configured in this way, the above Metacard would be displayed to the user.
Note that this particular configuration would not require any XACML rules to be present.
All of the attributes can be matched internally and there is no reason to call out to the external XACML processing engine.
For more complex decisions, it might be necessary to write a XACML policy to handle certain attributes.
7.6.2.2. Setting XACML Policies
To set up a XACML policy, place the desired XACML policy in the <distribution root>/etc/pdp/policies
directory and update the included access-policy.xml
to include the new policy.
This is the directory in which the PDP will look for XACML policies every 60 seconds.
See Developing XACML Policies for more information about custom XACML policies.
7.6.2.3. Catalog Filter Policy Plugins
Several Policy Plugins for catalog filtering exist currently: Metacard Attribute Security Policy Plugin and XML Attribute Security Policy Plugin. These Policy Plugin implementations allow an administrator to easily add filtering capabilities to some standard Metacard types for all Catalog operations. These plugins will place policy information on the Metacard itself that allows the Filter Plugin to restrict unauthorized users from viewing content they are not allowed to view.
7.7. Configuring User Interfaces
DDF has several user interfaces available for users.
7.7.1. Configuring Intrigue
Start here to configure Intrigue.
7.7.1.1. Configuring Default Layout for Intrigue
Intrigue includes several options for users to display search results. By default, users start with a 3D map and an Inspector to view details of results or groups of results. Add or remove additional visualizations to the default view through the Default Layout UI. Users can customize their individual views as well.
- 3D Map (Default)
-
Display a fully-interactive three-dimensional globe.
- 2D Map
-
Display a less resource-intensive two-dimensional map.
- Inspector (Default)
-
Display a view of detailed information about a search result.
- Histogram
-
Compare attributes of items in a search result set as a histogram.
- Table
-
Compare attributes of items in a search result set as a table.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Default Layout tab.
-
Add or Remove visualizations as desired.
-
To add a visualization, select the Add icon.
-
To remove a visualization, select the Delete icon on the tab for that visualization.
-
-
Select Save to complete.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Configuration tab.
-
Select
org.codice.ddf.catalog.ui
-
Edit "Visualizations" JSON as desired.
Example JSON:
[ { "name": "openlayers", "title": "2D Map", "icon": "map" }, { "name": "cesium", "title": "3D Map", "icon": "globe" }, { "name": "inspector", "title": "Inspector", "icon": "info" }, { "name": "histogram", "title": "Histogram", "icon": "bar-chart" }, { "name": "table", "title": "Table", "icon": "table" } ]
-
Select Save to complete.
7.7.1.2. Configuring Map Layers for Intrigue
Customize the look of the map displayed to users in Intrigue by adding or removing map layers through the Map Layers UI. Equivalent addition and deletion of a map layer can be found in Map Configuration for Intrigue.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Map Layers tab.
-
Add, Configure or Remove map layers as desired.
Adding a Map Layer translates to adding an Imagery Provider
-
Enter a unique alphanumeric Name (no special characters).
-
Enter the Provider URL for the server hosting the map layer instance.
-
Select Proxy if security policies or the tile server does not allow Cross-Origin Resource Sharing (CORS).
-
Select Allow Credential Formatting if map layer server prompts for credentials.
-
If selected, requests will fail if the server does not prompt for credentials.
-
-
Select from the list of available Provider Types.
-
Select a value for the Alpha to set the overall opacity of the map layer.
-
Setting Alpha to 0 will prevent the layer from loading.
-
-
Select Show to make the layer visible in Intrigue. (Deselect to hide.)
-
Select Transparent if tile images contain transparency.
To remove all map layers, select RESET.
-
Move layers Up and Down in loading order with the Arrow Icons associated with each layer.
Select Advanced Configuration to edit the JSON-formatted configuration directly. See Catalog UI Search Configurations for examples of map layer configurations.
External links to the specific API documentation of the map layer is also available from the Advanced Configuration menu.
7.7.1.3. Map Configuration for Intrigue
Customize the look of the map displayed to users in Intrigue through the Catalog UI Search. Equivalent addition and deletion of a map layer can be found in Configuring Map Layers for Intrigue.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Configuration tab.
-
Select the Catalog UI Search configuration.
-
Enter the properties of the map layer into the Imagery Provider in the proper syntax.
-
Example Imagery Provider Syntax:
{"type": "OSM", "url" "http://a.tile.openstreetmaps.org" "layers" ["layer1" "layer2"] "parameters" {"FORMAT" "image/png" "VERSION" "1.1.1"} "alpha" 0.5}
.-
"type": format of imagery provider.
-
"url": location of server hosting the imagery provider.
-
"layers": names of individual layers. (enclose list in square brackets`[ ]`).
-
"parameters": (enclose in braces
{}
)-
"FORMAT": image type used by imagery provider.
-
"VERSION": version of imagery provider to use.
-
"alpha": opacity of imagery provider layer.
-
-
-
-
Delete the properties in Imagery Provider text box.
-
Enter the properties into the Terrain Provider in the proper syntax.
-
A default Terrain Provider is provided:
{ "type": "CT", "url": "http://assets.agi.com/stk-terrain/tilesets/world/tiles" }
.-
"type": format of terrain provider.
-
"url": location of server hosting the terrain provider.
-
-
-
Check/Uncheck Show Gazetteer to control searching place names functionality.
-
Check/Uncheck Use Online Gazetteer to control Intrigue search gazetteer.
-
Unchecked: use local gazetteer service.
-
7.7.1.4. Configuring User Access to Ingest and Metadata for Intrigue
Intrigue lets the administrator control user access to ingest and metadata. The administrator can show or hide the uploader, letting them control whether users can ingest products. They can also choose whether or not users can edit existing metadata. By default, the uploader is available to users and editing is allowed.
Choose to hide or show the uploader. Note that hiding the uploader will remove the users' ability to ingest.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Configuration tab.
-
Select Catalog UI Search.
-
Select "Show Uploader".
-
Select Save to complete.
Allow or restrict the editing of metadata.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Configuration tab.
-
Select Catalog UI Search.
-
Select "Allow Editing".
-
Select Save to complete.
7.7.1.5. Configuring the Intrigue Upload Editor
The upload editor in Intrigue allows users to specify attribute overrides which should be applied on ingest. Administrators control the list of attributes that users may edit and can mark certain attributes as required. They may also disable the editor if desired.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Configuration tab.
-
Select Catalog UI Search.
-
Use the "Upload Editor: Attribute Configuration" field to configure the attributes shown in the editor.
-
Use the "Upload Editor: Required Attributes" field to mark attributes as required.
-
Select Save to complete.
See Intrigue Configurations for more information regarding these configurations.
The editor only appears if it has attributes to show. If the upload editing capability is not desired, simply remove all entries from the attribute configuration and the editor will be hidden.
7.7.1.6. Configuring Search Options for Intrigue
Intrigue provides a few options to control what metacards may be searched. By default, the user can perform searches that produce historical metacards, archived metacards, and metacards from the local catalog. However, administrators can disable searching for any of these types of metacards.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Configuration tab.
-
Select Catalog UI Search.
-
Scroll down to the "Disable Local Catalog" option with the other options below it.
-
To disable searching for a metacard type, check the corresponding box.
-
Select Save to complete.
7.7.1.7. Configuring Query Feedback for Intrigue
Intrigue provides an option to allow users to submit Query Feedback.
-
First, configure the Email Service to point to a mail server. See Email Service Configurations.
-
Navigate to the Admin Console.
-
Select the Search UI application.
-
Select the Configuration tab.
-
Select Catalog UI Search.
-
Select the Enable Query Feedback option to enable the query comments option for users in Intrigue.
-
Add a Query Feedback Email Subject Template.
-
Add a Query Feedback Email Body Template. The template may include HTML formatting.
-
Add the Query Feedback Email Destination.
-
Select the Save button.
The following keywords in the templates will be replaced with submission-specific values, or "Unknown" if unknown.
Template keyword | Replacement value |
---|---|
|
Username of the security subsystem (see Security Framework) |
|
Username of the user who submitted the Query Feedback |
|
Email of the user who submitted the Query Feedback |
|
Workspace ID of the query |
|
Workspace Name of the query |
|
Query |
|
Time of the query |
|
Status of the query |
|
Results of the query |
|
Comments provided by the user about the query |
-
Perform a search on any workspace.
-
Select the 3 dots on the results tab.
-
Choose the Submit Feedback option.
-
Add comments in the input box.
-
Select the Send button.
See Catalog UI Search Configurations for default Query Feedback configurations.
7.8. Configuring Federation
DDF is able to federate to other data sources, including other instances of DDF, with some simple configuration.
7.8.1. Enable SSL for Clients
In order for outbound secure connections (HTTPS) to be made from components like Federated Sources and Resource Readers configuration may need to be updated with keystores and security properties.
These values are configured in the <DDF_HOME>/etc/custom.system.properties
file.
The following values can be set:
Property | Sample Value | Description |
---|---|---|
|
|
The java keystore that contains the trusted public certificates for Certificate Authorities (CA’s) that can be used to validate SSL Connections for outbound TLS/SSL connections (e.g. HTTPS). When making outbound secure connections a handshake will be done with the remote secure server and the CA that is in the signing chain for the remote server’s certificate must be present in the trust store for the secure connection to be successful. |
|
|
This is the password for the truststore listed in the above property |
|
|
The keystore that contains the private key for the local server that can be used for signing, encryption, and SSL/TLS. |
|
|
The password for the keystore listed above |
|
|
The type of keystore |
|
|
The cipher suites that are supported when making outbound HTTPS connections |
|
|
The protocols that are supported when making outbound HTTPS connections |
|
|
The protocols that are supported when making inbound HTTPS connections |
|
'matched' |
For X.509 certificate based authentication (of non-exportable cipher suites), the DH key size matching the corresponding authentication key is used, except that the size must be between 1024 bits and 2048 bits. For example, if the public key size of an authentication certificate is 2048 bits, then the ephemeral DH key size should be 2048 bits unless the cipher suite is exportable. This key sizing scheme keeps the cryptographic strength consistent between authentication keys and key-exchange keys. |
Note
|
<DDF_HOME> DirectoryDDF is installed in the |
7.8.2. Configuring HTTP(S) Ports
To change HTTP or HTTPS ports from the default values, edit the custom.system.properties
file.
-
Open the file at <DDF_HOME>/etc/custom.system.properties
-
Change the value after the
=
to the desired port number(s):-
org.codice.ddf.system.httpsPort=8993
toorg.codice.ddf.system.httpsPort=<PORT>
-
org.codice.ddf.system.httpPort=8181
toorg.codice.ddf.system.httpPort=<PORT>
-
-
Restart DDF for changes to take effect.
Important
|
Do not use the Admin Console to change the HTTP port. While the Admin Console’s Pax Web Runtime offers this configuration option, it has proven to be unreliable and may crash the system. |
7.8.3. Configuring HTTP Proxy
The platform-http-proxy
feature proxies https to http for clients that cannot use HTTPS and should not have HTTP enabled for the entire container via the etc/org.ops4j.pax.web.cfg
file.
-
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Select
platform-http-proxy
. -
Select the Play button to the right of the word “Uninstalled”
-
Type the command
feature:install platform-http-proxy
-
Select Configuration tab.
-
Select HTTP to HTTPS Proxy Settings
-
Enter the Hostname to use for HTTPS connection in the proxy.
-
-
Click Save changes.
Note
|
HTTP Proxy and Hostname
The hostname should be set by default. Only configure the proxy if this is not working. |
7.8.4. Federation Strategy
A federation strategy federates a query to all of the Remote Sources in the query’s list, processes the results in a unique way, and then returns the results to the client. For example, implementations can choose to halt processing until all results return and then perform a mass sort or return the results back to the client as soon as they are received back from a Federated Source.
An endpoint can optionally specify the federation strategy to use when it invokes the query operation. Otherwise, the Catalog provides a default federation strategy that will be used: the Catalog Federation Strategy.
7.8.4.1. Configuring Federation Strategy
The Catalog Federation Strategy configuration can be found in the Admin Console.
-
Navigate to Admin Console.
-
Select Catalog
-
Select Configuration
-
Select Catalog Federation Strategy.
See Federation Strategy configurations for all possible configurations.
7.8.4.1.1. Catalog Federation Strategy
The Catalog Federation Strategy is the default federation strategy and is based on sorting metacards by the sorting parameter specified in the federated query.
The possible sorting values are:
-
metacard’s effective date/time
-
temporal data in the query result
-
distance data in the query result
-
relevance of the query result
The supported sorting orders are ascending and descending.
The default sorting value/order automatically used is relevance descending.
Warning
|
The Catalog Federation Strategy expects the results returned from the Source to be sorted based on whatever sorting criteria were specified. If a metadata record in the query results contains null values for the sorting criteria elements, the Catalog Federation Strategy expects that result to come at the end of the result list. |
7.8.5. Connecting to Sources
A source is a system consisting of a catalog containing Metacards.
Catalog sources are used to connect Catalog components to data sources, local and remote. Sources act as proxies to the actual external data sources, e.g., a RDBMS database or a NoSQL database.
- Remote Source
-
Read-only data sources that support query operations but cannot be used to create, update, or delete metacards.
- Federated Sources
-
A federated source is a remote source that can be included in federated queries by request or as part of an enterprise query. Federated sources support query and site information operations only. Catalog modification operations, such as create, update, and delete, are not allowed. Federated sources also expose an event service, which allows the Catalog Framework to subscribe to event notifications when metacards are created, updated, and deleted.
Catalog instances can also be federated to each other. Therefore, a Catalog can also act as a federated source to another Catalog.
- Connected Sources
-
A Connected Source is a local or remote source that is always included in every local and enterprise query, but is hidden from being queried individually. A connected source’s identifier is removed in all query results by replacing it with DDF’s source identifier. The Catalog Framework does not reveal a connected source as a separate source when returning source information responses.
- Catalog Providers
-
A Catalog Provider is used to interact with data providers, such as files systems or databases, to query, create, update, or delete data. The provider also translates between DDF objects and native data formats.
All sources, including federated source and connected source, support queries, but a Catalog provider also allows metacards to be created, updated, and deleted. A Catalog provider typically connects to an external application or a storage system (e.g., a database), acting as a proxy for all catalog operations.
- Catalog Stores
-
A Catalog Store is an editable store that is either local or remote.
The following Federated Sources are available in a standard installation of DDF:
- Federated Source for Atlassian Confluence®
-
Retrieve pages, comments, and attachments from an Atlassian Confluence® REST API.
- CSW Specification Profile Federated Source
-
Queries a CSW version 2.0.2 compliant service.
- CSW Federation Profile Source
-
Queries a CSW version 2.0.2 compliant service.
- GMD CSW Source
-
Queries a GMD CSW APISO compliant service.
- OpenSearch Source
-
Performs OpenSearch queries for metadata.
- WFS 1.0 Source
-
Allows for requests for geographical features across the web.
- WFS 1.1 Source
-
Allows for requests for geographical features across the web.
- WFS 2.0 Source
-
Allows for requests for geographical features across the web.
The following Connected Sources are available in a standard installation of DDF:
- WFS 1.0 Source
-
Allows for requests for geographical features across the web.
- WFS 1.1 Source
-
Allows for requests for geographical features across the web.
- WFS 2.0 Source
-
Allows for requests for geographical features across the web.
The following Catalog Stores are available in a standard installation of DDF:
- Registry Store
-
Allows CSW messages to be turned into usable Registry metacards and for those metacards to be turned back into CSW messages.
The following Catalog Providers are available in a standard installation of DDF:
- Solr Catalog Provider
-
Uses Solr as a catalog.
The following Storage Providers are available in a standard installation of DDF:
- Content File System Storage Provider
-
.Sources Details Availability and configuration details of available sources.
7.8.5.1. Federated Source for Atlassian Confluence(R)
The Confluence source provides a Federated Source to retrieve pages, comments, and attachments from an Atlassian Confluence® REST API and turns the results into Metacards the system can use. The Confluence source does provide a Connected Source interface but its functionality has not been verified.
Confluence Source has been tested against the following versions of Confluence with REST API v2
-
Confluence 1000.444.5 (Cloud)
-
Confluence 5.10.6 (Server)
-
Confluence 5.10.7 (Server)
The Confluence Federated Source is installed by default with a standard installation in the Catalog application.
Add a New Confluence Federated Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Add a New source.
-
Name the New source.
-
Select Confluence Federated Source from Binding Configurations.
Configure an Existing Confluence Federated Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See Confluence Federated Source configurations for all possible configurations.
Important
|
If an additional attribute is not part of the Confluence metacard type or injected, the attribute will not be added to the metacard. |
Most of the fields that can be queried on Confluence have some sort of restriction on them. Most of the fields do not support the like
aka ~
operation so the source will convert like
queries to equal
queries for attributes that don’t support like
. If the source receives a query with attributes it doesn’t understand, it will just ignore them. If the query doesn’t contain any attributes that map to Confluence search attributes, an empty result set will be returned.
Depending on your version of Confluence, when downloading attachments you might get redirected to a different download URL. The default URLResourceReader configuration allows redirects, but if the option was disabled in the past, the download will fail. This can be fixed by re-enabling redirects in the URLResourceReader
configuration.
7.8.5.2. CSW Specification Profile Federated Source
The CSW Specification Profile Federated Source should be used when federating to an external (non-DDF-based) CSW (version 2.0.2) compliant service.
Add a New CSW Specification Profile Federated Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Add a New source.
-
Name the New source.
-
Select CSW Specification Profile Federated Source from Source Type.
Configure an Existing CSW Specification Profile Federated Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See CSW Specification Profile Federated Source configurations for all possible configurations.
-
Nearest neighbor spatial searches are not supported.
7.8.5.3. CSW Federation Profile Source
The CSW Federation Profile Source is DDF’s CSW Federation Profile which supports the ability to search collections of descriptive information (metadata) for data, services, and related information objects.
Use the CSW Federation Profile Source when federating to a DDF-based system.
Configure the CSW Federation Profile Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Add a New source.
-
Name the New source.
-
Select CSW Specification Profile Federated Source from Source Type.
Configure an Existing CSW Federated Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See CSW Federation Profile Source configurations for all possible configurations.
-
Nearest neighbor spatial searches are not supported.
7.8.5.4. Content File System Storage Provider
The Content File System Storage Provider is the default Storage Provider included with DDF
The Content File System Storage Provider is installed by default with the Catalog application.
To configure the Content File System Storage Provider:
-
Navigate to the Admin Console.
-
Select Catalog.
-
Select Configuration.
-
Select Content File System Storage Provider.
See Content File System Storage Provider configurations for all possible configurations.
7.8.5.5. GMD CSW Source
The Geographic MetaData extensible markup language (GMD) CSW source supports the ability to search collections of descriptive information (metadata) for data, services, and related information objects, based on the Application Profile ISO 19115/ISO19119 .
Use the GMD CSW source if querying a GMD CSW APISO compliant service.
The GMD CSW source is installed by default with a standard installation in the Spatial application.
Configure a new GMD CSW APISO v2.0.2 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Add a New source.
-
Name the New source.
-
Select GMD CSW ISO Federated Source from Binding Configurations.
Configure an existing GMD CSW APISO v2.0.2 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See GMD CSW APISO v2.0.2 Source configurations for all possible configurations.
7.8.5.6. OpenSearch Source
The OpenSearch source provides a Federated Source that has the capability to do OpenSearch queries for metadata from Content Discovery and Retrieval (CDR) Search V1.1 compliant sources. The OpenSearch source does not provide a Connected Source interface.
The OpenSearch Source is installed by default with a standard installation in the Catalog application.
Configure a new OpenSearch Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Add a New source.
-
Name the New source.
-
Select OpenSearch Source from Binding Configurations.
Configure an existing OpenSearch Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See OpenSearch Source configurations for all possible configurations.
Use the OpenSearch source if querying a CDR-compliant search service is desired.
Element | OpenSearch HTTP Parameter | DDF Data Location |
---|---|---|
searchTerms |
|
Pulled from the query and encoded in UTF-8. |
routeTo |
|
Pulled from the query. |
maxResults |
|
Pulled from the query. |
count |
|
Pulled from the query. |
startIndex |
|
Pulled from the query. |
maxTimeout |
|
Pulled from the query. |
userDN |
|
DDF subject |
lat |
|
Pulled from the query if it is a point-radius query and the radius is > 0. |
lon |
|
|
radius |
|
|
box |
|
Pulled from the query if it is a bounding-box query. |
geometry |
|
Pulled from the DDF query and combined as a geometry collection if multiple spatial query exist. |
polygon |
|
According to the OpenSearch Geo Specification this is deprecated. Use the geometry parameter instead. |
start |
|
Pulled from the query if the query has temporal criteria for modified. |
end |
|
|
filter |
|
Pulled from the query. |
sort |
|
Calculated from the query.
Format: |
The OpenSearch source does not provide a Connected Source interface.
7.8.5.7. Registry Store
The Registry Store is the interface that allows CSW messages to be turned into usable Registry metacards and for those metacards to be turned back into CSW messages.
The Registry Store is installed by default with the Registry application.
To configure the Registry store:
-
Navigate to the Admin Console.
-
Select Registry.
-
Select the Remote Registries Tab and click the Add button.
-
ALTERNATIVELY: Select the Configuration Tab and select Registry Store.
-
7.8.5.8. Solr Catalog Provider
The Solr Catalog Provider is included with a standard installation of DDF. There are two configurations available:
DDF is bundled with a distribution of Apache Solr. This distribution includes special JAR libraries used by DDF. This DDF scripts manage the starting and stopping of the Solr server. Considerations include:
-
No configuration necessary. Simply start DDF and DDF manages starting and stopping the Solr server.
-
Backup can be performed using DDF console’s
backup
command. -
This configuration cannot be scaled larger than the single Solr server.
-
All data is located inside the {$branding} home directory. If the Solr index grows large, the storage volume may run low on space.
No installation is required because DDF includes a distribution of Apache Solr.
No configuration.
Solr Cloud is a cluster of distributed Solr servers used for high availability and scalability. If the DDF needs to be available with little or no downtime, then the Solr Cloud configuration should be used. The general considerations for selecting this configuration are:
-
SolrCloud can scale to support over 2 billion indexed documents.
-
Has network overhead and requires additional protection to be secure.
-
Installation is more involved (requires Zookeeper)
-
Configuration and administration is more complex due to replication, sharding, etc.
-
No way to backup currently, but will automatically recover from system failure.
Configuration shared between Solr Server instances is managed by Zookeeper. Zookeeper helps manage the overall structure.
Note
|
The instructions on setting up Solr Cloud for DDF only include setup in a *NIX environment. |
Before Solr Cloud can be installed:
-
ZooKeeper 3.4.5 (Refer to https://zookeeper.apache.org/doc/r3.1.2/zookeeperStarted.html#sc_Download for installation instructions.)
-
*NIX environment
-
JDK 8 or greater
Note
|
A minimum of three Zookeeper nodes required. Three Zookeeper nodes are needed to form a quorum. A three Zookeeper ensemble allows for a single server to fail and the service will still be available. More Zookeeper nodes can be added to achieve greater fault tolerance. The total number of nodes must always be an odd number. See Setting Up an External Zoo Keeper Ensemble for more information. |
Before starting the install procedure, download the extension jars. The jars are needed to support geospatial and xpath queries and need to be installed on every Solr server instance after the Solr Cloud installation instructions have been followed.
The JARs can be found here:
Repeat the following procedure for each Solr server instance that will be part of the Solr Cloud cluster:
-
Refer to https://cwiki.apache.org/confluence/display/solr/Apache+Solr+Reference+Guide for installation instructions.
-
Copy
jts-core-1.15.0.jar
to:<SOLR_INSTALL_DIR>/server/solr-webapp/webapp/WEB-INF/lib/
. -
Copy
solr-xpath-2.21.6.jar
to:<SOLR_INSTALL_DIR>/plugins/
.
Note
|
A minimum of two Solr server instances is required. Each Solr server instance must have a minimum of two shards. Having two Solr server instances guarantees that at least one Solr server is available if one fails. The two shards enables the document mapping to be restored if one shard becomes unavailable. |
-
On the DDF server, edit
<DDF_HOME>/etc/custom.system.properties
:-
Comment out the Solr Client Configuration for Http Solr Client section.
-
Uncomment the section for the Cloud Solr Client:
-
Set
solr.cloud.zookeeper
to<ZOOKEEPER_1_HOSTNAME>:<PORT_NUMBER>
,<ZOOKEEPER_2_HOSTNAME>:<PORT_NUMBER>
,<ZOOKEEPER_n_HOSTNAME>:<PORT_NUMBER>
-
Set
solr.data.dir
to the desired data directory.
-
solr.client = CloudSolrClient solr.data.dir = ${karaf.home}/data/solr solr.cloud.zookeeper = zk1:2181,zk2:2181,zk3:2181
7.8.5.9. WFS 1.0 Source
The WFS Source allows for requests for geographical features across the web using platform-independent calls.
A Web Feature Service (WFS) source is an implementation of the FederatedSource
interface provided by the DDF Framework.
Use the WFS Source if querying a WFS version 1.0.0 compliant service.
The WFS v1.0.0 Source is installed by default with a standard installation in the Spatial application.
Configure a new WFS v1.0.0 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Add a New source.
-
Name the New source.
-
Select WFS v1.0.0 Source from Binding Configurations.
Configure an existing WFS v1.0.0 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See WFS v.1.0 Federated Source configurations or WFS v1.0 Connected Source configurations for all possible configurations.a
The WFS URL must match the endpoint for the service being used. The type of service and version are added automatically, so they do not need to be included. Some servers will throw an exception if they are included twice, so do not include those.
The syntax depends on the server.
However, in most cases, the syntax will be everything before the ?
character in the URL that corresponds to the GetCapabilities
query.
http://www.example.org:8080/geoserver/ows?service=wfs&version=1.0.0&request=GetCapabilities
In this case, the WFS URL would be: http://www.example.org:8080/geoserver/ows
7.8.5.10. WFS 1.1 Source
The WFS Source allows for requests for geographical features across the web using platform-independent calls.
A Web Feature Service (WFS) source is an implementation of the FederatedSource
interface provided by the DDF Framework.
Use the WFS Source if querying a WFS version 1.1.0 compliant service.
The WFS v1.1.0 Source is installed by default with a standard installation in the Spatial application.
Configure a new WFS v1.1.0 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Add a New source.
-
Name the New source.
-
Select WFS v1.1.0 Source from Binding Configurations.
Configure an existing WFS v1.1.0 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See WFS v.1.1 Federated Source configurations for all possible configurations.
The WFS URL must match the endpoint for the service being used. The type of service and version are added automatically, so they do not need to be included. Some servers will throw an exception if they are included twice, so do not include those.
The syntax depends on the server.
However, in most cases, the syntax will be everything before the ?
character in the URL that corresponds to the GetCapabilities
query.
http://www.example.org:8080/geoserver/wfs?service=wfs&version=1.1.0&request=GetCapabilities
In this case, the WFS URL would be: http://www.example.org:8080/geoserver/wfs
The WFS v1.1.0 Source supports mapping metacard attributes to WFS feature properties for queries (GetFeature requests) to the WFS server.
The source uses a MetacardMapper
service to determine how to map a given metacard attribute in a query to a feature property the WFS server understands.
It looks for a MetacardMapper
whose getFeatureType()
matches the feature type being queried.
Any MetacardMapper
service implementation will work, but DDF provides one in the Spatial application called Metacard to WFS Feature Map.
7.8.5.11. WFS 2.0 Source
The WFS 2.0 Source allows for requests for geographical features across the web using platform-independent calls.
Use the WFS Source if querying a WFS version 2.0.0 compliant service. Also see Working with WFS Sources.
The WFS v2.0.0 Source is installed by default with a standard installation in the Spatial application.
Configure a new WFS v2.0.0 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Add a new source.
-
Name the new source.
-
Select WFS v2.0.0 Source from Binding Configurations.
Configure an existing WFS v2.0.0 Source through the Admin Console:
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Sources tab.
-
Select the name of the source to edit.
See WFS v.2.0 Federated source configurations or WFS v2.0 Connected source configurations for all possible configurations.
The WFS URL must match the endpoint for the service being used. The type of service and version is added automatically, so they do not need to be included. Some servers will throw an exception if they are included twice, so do not include those.
The syntax depends on the server.
However, in most cases, the syntax will be everything before the ?
character in the URL that corresponds to the GetCapabilities
query.
http://www.example.org:8080/geoserver/ows?service=wfs&version=2.0.0&request=GetCapabilities
In this case, the WFS URL would be
http://www.example.org:8080/geoserver/ows
The WFS 2.0 Source allows for virtually any schema to be used to describe a feature.
A feature is roughly equivalent to a metacard. The MetacardMapper
was added to allow an administrator to configure which feature properties map to which metacard attributes.
MetacardMapper
Use the WFS MetacardMapper
to configure which feature properties map to which metacard attributes when querying a WFS version 2.0.0 compliant service.
When feature collection responses are returned from WFS sources, a default mapping occurs which places the feature properties into metacard attributes, which are then presented to the user via DDF.
There can be situations where this automatic mapping is not optimal for your solution.
Custom mappings of feature property responses to metacard attributes can be achieved through the MetacardMapper
.
The MetacardMapper
is set by creating a feature file configuration which specifies the appropriate mapping. The mappings are specific to a given feature type.
MetacardMapper
The WFS MetacardMapper
is installed by default with a standard installation in the Spatial application.
MetacardMapper
There are two ways to configure the MetacardMapper
:
-
The Configuration Admin available in the Admin Console.
-
Placing a
feature.xml
file in thedeploy
directory.
The following shows how to configure the MetacardMapper
to be used with the sample data provided with GeoServer.
This configuration shows a custom mapping for the feature type ‘states’.
For the given type, we are taking the feature property ‘STATE_NAME’ and mapping it to the metacard attribute ‘title’.
In this particular case, since we mapped the state name to title in the metacard, it will now be fully searchable.
MetacardMapper
Configuration Within a feature.xml
file:
1
2
3
4
5
6
7
<feature name="geoserver-states" version="2.21.6"
description="WFS Feature to Metacard mappings for GeoServer Example {http://www.openplans.org/topp}states">
<config name="org.codice.ddf.spatial.ogc.wfs.catalog.mapper.MetacardMapper-geoserver.http://www.openplans.org/topp.states">
featureType = {http://www.openplans.org/topp}states
titleMapping = STATE_NAME
</config>
</feature>
7.8.6. Configuring Endpoints
Configure endpoints to enable external systems to send and receive content and metadata from DDF.
7.8.6.1. Configuring Catalog REST Endpoint
The Catalog REST endpoint allows clients to perform operations on the Catalog using REST.
To install the Catalog REST endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Install the
catalog-rest-endpoint
feature.
The Catalog REST endpoint has no configurable properties. It can only be installed or uninstalled.
7.8.6.2. Configuring CSW Endpoint
The CSW endpoint enables a client to search collections of descriptive information (metadata) about geospatial data and services.
To install the CSW endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Install the
csw-endpoint
feature.
To control the number of threads used for parallel processing of transactions,
set the org.codice.ddf.spatial.ogc.csw.catalog.endpoint.threadpool
system property in custom.system.properties.
The default thread pool is 2 * Number Processors.
7.8.6.3. Configuring FTP Endpoint
The FTP endpoint provides a method for ingesting files directly into the DDF Catalog using the FTP protocol The files sent over FTP are not first written to the file system, as the Directory Monitor does, but instead the FTP stream of the file is ingested directly into the DDF catalog, thus avoiding extra I/O overhead.
To install the FTP endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Install the
catalog-ftp
feature.
To configure the FTP endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Select FTP Endpoint.
See FTP Endpoint configurations for all possible configurations.
7.8.6.4. Configuring KML Endpoint
Keyhole Markup Language (KML) is an XML notation for describing geographic annotation and visualization for 2- and 3- dimensional maps.
The root network link will create a network link for each configured source, including the local catalog. The individual source network links will perform a query against the OpenSearch Endpoint periodically based on the current view in the KML client. The query parameters for this query are obtained by a bounding box generated by Google Earth. The root network link will refresh every 12 hours or can be forced to refresh. As a user changes their current view, the query will be re-executed with the bounding box of the new view. (This query gets re-executed two seconds after the user stops moving the view.)
This KML Network Link endpoint has the ability to serve up custom KML style documents and Icons to be used within that document. The KML style document must be a valid XML document containing a KML style. The KML Icons should be placed in a single level directory and must be an image type (png, jpg, tif, etc.). The Description will be displayed as a pop-up from the root network link on Google Earth. This may contain the general purpose of the network and URLs to external resources.
To install the KML endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Install the
spatial-kml
feature.
To configure the KML endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Select KML Endpoint.
See KML Endpoint configurations for all possible configurations.
7.8.6.5. Configuring OpenSearch Endpoint
The OpenSearch endpoint enables a client to send query parameters and receive search results. This endpoint uses the input query parameters to create an OpenSearch query. The client does not need to specify all of the query parameters, only the query parameters of interest.
To install the KML endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Install the
catalog-opensearch-endpoint
feature.
The OpenSearch endpoint has no configurable properties. It can only be installed or uninstalled.
7.8.6.6. Configuring WPS Endpoint
The WPS endpoint enables a client to execute and monitor long running processes.
To install the WPS endpoint:
-
Navigate to the Admin Console.
-
Select System.
-
Select Features.
-
Install the
spatial-wps
feature.
The WPS endpoint has no configurable properties. It can only be installed or uninstalled.
7.8.6.7. Compression Services
DDF supports compression of outgoing and incoming messages through the Compression Services. These compression services are based on CXF message encoding.
The formats supported in DDF are:
- gzip
-
Adds GZip compression to messages through CXF components. Code comes with CXF.
- exi
-
Adds Efficient XML Interchange (EXI) support to outgoing responses. EXI is an W3C standard for XML encoding that shrinks xml to a smaller size than normal GZip compression.
To Install a compression service:
-
Navigate to the Admin Console.
-
Select the System tab.
-
Select the Features tab.
-
Start the service for the desired compression format:
-
compression-exi
-
compression-gzip
-
Warning
|
The compression services either need to be installed BEFORE the desired CXF service is started or the CXF service needs to be refreshed / restarted after the compression service is installed. |
Compression services have no configurable properties. They can only be installed or uninstalled.
7.8.7. Federating Through a Registry
Another approach to configuring federation is to use the Registry application to locate sources in a network/enterprise. See Registry Application Reference for details on installing the Registry application. Use the registry to subscribe to and federate with other instances of DDF.
Note
|
The Node Information and Remote Registries tabs appear in both the Registry application and the Catalog application. |
Note
|
For direct federation configuration, sources and registries can be configured at https://{FQDN}:{PORT}/admin/federation. |
7.8.7.1. Configuring Identity Node
The "Identity Node" is the local DDF instance. Configure the information to share with other registries/nodes.
-
Navigate to Registry (or Catalog) application.
-
Navigate to Node Information tab.
-
Click the name of the identity node.
-
Complete all required and any desired optional fields.
-
Add any desired service bindings under the Services tab.
-
-
Click Save.
Field | Description | Type | Required |
---|---|---|---|
Node Name |
This node’s name as it should appear to external systems |
string |
yes |
Node Description |
Short description for this node |
string |
yes |
Node Version |
This node’s Version |
string |
yes |
Security Attributes |
Security attributes associated with this node. |
String |
|
Last Updated |
Date this entry’s data was last updated |
Date |
|
Live Date |
Date indicating when this node went live or operational |
Date |
|
Custom Fields |
click Add button to add custom fields |
Configurable |
no |
Associations |
click Add button to add associations |
Configurable |
no |
Field | Description | Type | Required |
---|---|---|---|
Organization Name |
This organization’s name |
string |
yes |
Address |
This organization’s primary address |
Expand to enter address information |
yes |
Telephone Number |
Primary contact number for this organization |
no |
|
Primary contact email for this organization |
no |
||
Custom Fields |
click Add button to add custom fields |
Configurable |
no |
Associations |
click Add button to add associations |
Configurable |
no |
Field | Description | Type | Required |
---|---|---|---|
Contact Title |
Contact Title |
String |
yes |
Contact First Name |
Contact First Name |
String |
yes |
Contact Last Name |
Contact Last Name |
String |
yes |
Address |
Address for listed contact |
String |
minimum one |
Phone number |
Contact phone number |
minimum one |
|
Contact email |
String |
minimum one |
|
Custom Fields |
click Add button to add custom fields |
Configurable |
no |
Associations |
click Add button to add associations |
Configurable |
no |
Field | Description | Type | Required |
---|---|---|---|
Content Name |
Name for this metadata content |
string |
yes |
Content Description |
Short description for this metadata content |
string |
no |
Content Object Type |
The kind of content object this will be. Default value should be used in most cases. |
string |
yes |
Custom Fields |
click Add button to add custom fields |
Configurable |
no |
Associations |
click Add button to add associations |
Configurable |
no |
7.8.7.1.1. Adding a Service Binding to a Node
Advertise the methods other nodes use to connect to the local DDF instance.
-
Navigate to Admin Console.
-
Select Registry or Catalog.
-
(Node Information tab is editable from either application.)
-
-
Click the name of the desired local node.
-
Click the Services tab.
-
Click Add to add a service.
-
Expand new Service.
-
Enter Service name and details.
-
Click Add to add binding.
-
Select Service Binding type.
-
Select one of the defaults or empty for a custom service binding.
-
If selecting empty, fill in all required fields.
-
-
Click Save.
7.8.7.2. Publishing to Other Nodes
Send details about the local DDF instance to other nodes.
-
Navigate to the Remote Registries tab in either Registry or Catalog application.
-
Click Add to add a remote registry.
-
Enter Registry Service (CSW) URL.
-
Confirm Allow Push is checked.
-
Click Add to save the changes.
-
Navigate to the Sources Tab in Catalog App
-
Click desired node to be published.
-
Under Operations, click the *Publish to … * link that corresponds to the desired registry.
7.8.7.3. Subscribing to Another Node
Receive details about another node.
-
Navigate to the Remote Registries tab in either Registry or Catalog application.
-
Click Add to add a remote registry.
-
Add the URL to access node.
-
Enter any needed credentials in the Username/password fields.
-
Click Save/Add.
Update the configuration of an existing subscription.
-
Navigate to the Remote Registries tab in either Registry or Catalog application.
-
Click the name of the desired subscription.
-
Make changes.
-
Click Save.
Remove a subscription.
-
Click the Delete icon at the top of the Remote Registries tab.
-
Check the boxes of the Registry Nodes to be deleted.
-
Select the Delete button.
7.9. Environment Hardening
-
Required Step for Security Hardening
Important
|
It is recommended to apply the following security mitigations to the DDF. |
7.9.1. Known Issues with Environment Hardening
The session timeout should be configured longer than the UI polling time or you may get session timeout errors in the UI.
Protocol/Type |
Risk |
Mitigation |
||||
JMX |
tampering, information disclosure, and unauthorized access |
|
||||
File System Access |
tampering, information disclosure, and denial of service |
Set OS File permissions under the If Caching is installed:
On system: ensure that not everyone can change ACLs on your object. |
||||
SSH |
tampering, information disclosure, and denial of service |
By default, SSH access to DDF is only enabled to connections originating from the same
host running DDF.
For remote access to DDF,
first establish an SSH session with the host running
DDF. From within that session, initiate a new SSH connection (to localhost), and use
the To allow direct remote access to the DDF shell from any host, change the value of the
SSH can also be authenticated and authorized through an external Realm,
such as LDAP. This can be accomplished by editing the By definition, all connections over SSH will be authenticated and authorized and secure from eavesdropping.
Set |
||||
SSL/TLS |
man-in-the-middle, information disclosure |
Update the
|
||||
Session Inactivity Timeout |
unauthorized access |
Update the Session configuration to have no greater than a 10 minute Session Timeout.
|
||||
Shell Command Access |
command injection |
By default, some shell commands are disabled in order to secure the system.
DDF includes a whitelist of allowed shell commands in
By default, this list includes commands that are whitelisted only to administrators:
|
7.10. Configuring for Special Deployments
In addition to standard configurations, several specialized configurations are possible for specific uses of DDF.
7.10.1. Multiple Installations
One common specialized configuration is installing multiple instances of DDF.
7.10.1.1. Reusing Configurations
The Migration Export/Import capability allows administrators to export the current DDF configuration and use it to restore the same state for either a brand new installation or a second node for a Highly Available Cluster.
Important
|
There are some key limitations when following this process to reuse configurations for a different versions of DDF. See Reusing Configurations Across Different Versions below. |
To export the current configuration settings:
-
Run the command migration:export from the Command Console.
-
Files named
ddf-2.21.6.dar
,ddf-2.21.6.dar.key
, andddf-2.21.6.dar.sha256
will be created in theexported
directory underneath<DDF_HOME>
. The.dar
file contains the encrypted information. The.key
and.sha256
files contains the encryption key and a validation checksum. Copy the '.dar' file to a secure location and copy the '.key' and '.sha256' to a different secure location. Keeping all 3 files together represents a security risk and should be avoided.
To import previously exported configuration settings:
-
Unzip the DDF distribution.
-
Restore all external files, softlinks, and directories that would not have been exported and for which warnings would have been generated during export. This could include (but is not limited to) external certificates or monitored directories.
-
Start up the newly unzipped DDF distribution.
-
Make sure to install and re-enable the DDF service on the new system if it was installed and enabled on the original system.
-
Copy the previously exported files from your secure locations to the
exported
directory underneath<DDF_HOME>
. -
Either:
-
If an administrator wishes to restore the original profile along with the configuration (experimental, see 'NOTE' below this list):
-
Run the command migration:import with the option
--profile
from the Command Console (see 'NOTE' below this list)
-
-
Otherwise:
-
Step through the installation process one of 2 ways:
-
If network profile needs to be configured, install through the UI Admin Console.
-
Else, install by running the command
profile:install standard
in the Command Console.
-
-
Run the command migration:import from the Command Console.
-
-
-
DDF will automatically restart if the command is successful. Otherwise address any generated warnings before manually restarting DDF.
Note
|
The 'Experimental' in this context denotes the continuing development of using migration:import along with --profile to restore the original profile with the configuration. |
It is possible to decrypt the previously exported configuration settings but doing so is insecure and appropriate measures should be taken to secure the resulting decrypted file. To decrypt the exported file:
-
Copy all 3 exported files (i.e.
.dar
,.key
, and.sha256
) to theexported
directory underneath<DDF_HOME>
. -
Run the command migration:decrypt from the Command Console.
-
A file named
ddf-2.21.6.zip
will be created in theexported
directory underneath<DDF_HOME>
. This file represents the decrypted version of the.dar
file.
Important
|
|
7.10.1.1.1. Reusing Configurations Across Different Versions
The same step-by-step process above can be followed when migrating configurations between DDF instances of different versions, with a few key constraints:
-
Only a subset of configuration files are currently imported:
-
Files under
etc/ws-security
-
Files under
etc/pdp
-
etc/users.attributes
andetc/users.properties
-
security/configurations.policy
-
etc/system.properties
-
etc/custom.system.properties
(thesolr.password
property will be preserved) -
Keystores
-
Truststores
-
Service wrapper
*.conf
files, if the DDF is installed as a service -
Select Admin Console configurations, including:
-
Content Directory Monitor
-
URL Resource Reader
-
Web Context Policy Manager
-
Guest Claims Configuration
-
Security STS Server
-
Session
-
Catalog Federation Strategy
-
Catalog Standard Framework
-
Metacard Validation Filter Plugin
-
Metacard Validation Marker Plugin
-
All Catalog Source configurations
-
All Registry configurations
WarningIf a supported configuration is being imported across versions, any corresponding .config
files in theetc
directory will not be put into theetc
directory of the importing system.
-
-
-
There is a list of specific DDF versions that have been tested that can be found in
etc/migration.properties
under the propertysupported.versions
, as a comma-delimited list. The system will only allow importing configurations from those versions.
7.10.1.2. Isolating Solr Cloud and Zookeeper
-
Required Step for Security Hardening (if using Solr Cloud/Zookeeper)
Zookeeper cannot use secure (SSL/TLS) connection. The configuration information that Zookeeper sends and receives is vulnerable to network sniffing. Also, the connections between the local Solr Catalog service and the Solr Cloud is not necessarily secure. The connections between Solr Cloud nodes are not necessarily secure. Any unencrypted network traffic is vulnerable to sniffing attacks. To use Solr Cloud and Zookeeper securely, these processes must be isolated on the network, or their communications must be encrypted by other means. The DDF process must be visible on the network to allow authorized parties to interact with it.
-
Create a private network for Solr Cloud and Zookeeper. Only DDF is allowed to contact devices inside the private network.
-
Use IPsec to encrypt the connections between DDF, Solr Cloud nodes, and Zookeeper nodes.
-
Put DDF, Solr Cloud and Zookeeper behind a firewall that only allows access to DDF.
7.10.2. Configuring for a Fanout Proxy
Optionally, configure DDF as a fanout proxy such that only queries and resource retrieval requests are processed and create/update/delete requests are rejected. All queries are enterprise queries and no catalog provider needs to be configured.
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select the Configuration tab.
-
Select Catalog Standard Framework.
-
Select Enable Fanout Proxy.
-
Save changes.
DDF is now operating as a fanout proxy. Only queries and resource retrieval requests will be allowed. All queries will be federated. Create, update, and delete requests will not be allowed, even if a Catalog Provider was configured prior to the reconfiguration as a fanout.
7.10.3. Standalone Security Token Service (STS) Installation
To run a STS-only DDF installation, uninstall the catalog components that are not being used. The following list displays the features that can be uninstalled to minimize the runtime size of DDF in an STS-only mode. This list is not a comprehensive list of every feature that can be uninstalled; it is a list of the larger components that can be uninstalled without impacting the STS functionality.
-
catalog-core-standardframework
-
catalog-opensearch-endpoint
-
catalog-opensearch-souce
-
catalog-rest-endpoint
7.10.4. Configuring for a Highly Available Cluster
This section describes how to make configuration changes after the initial setup for a DDF in a Highly Available Cluster.
In a Highly Available Cluster, configuration changes must be made on both DDF nodes. The changes can still be made in the standard ways via the Admin Console, the Command Line, or the file system.
Note
|
Changes made in the Admin Console must be made through the HTTP proxy. This means that the below steps should be followed to make a change in the Admin Console:
|
7.11. Configuring UI Themes
The optional configurations in this section cover minor changes that can be made to optimize DDF appearance.
7.11.1. Landing Page
The Landing Page is the first page presented to users of DDF. It is customizable to allow adding organizationally-relevant content.
7.11.1.1. Installing the Landing Page
The Landing Page is installed by default with a standard installation.
7.11.1.2. Configuring the Landing Page
The DDF landing page offers a starting point and general information for a DDF node.
It is accessible at /(index|home|landing(.htm|html))
.
7.11.1.3. Customizing the Landing Page
Configure the Landing Page from the Admin Console:
-
Navigate to the Admin Console.
-
Select Platform Application.
-
Select Configuration tab.
-
Select Landing Page.
Configure important landing page items such as branding logo, contact information, description, and additional links.
See Landing Page configurations for all possible configurations.
7.11.2. Configuring Logout Page
The logout pages is presented to users through the navigation of DDF and has a changeable timeout value.
-
Navigate to the Admin Console.
-
Select Security Application.
-
Select Configuration tab.
-
Select Logout Page.
The customizable feature of the logout page is the Logout Page Time Out. This is the time limit the IDP client will wait for a user to click log out on the logout page. Any requests that take longer than this time for the user to submit will be rejected.
-
Default value: 3600000 (milliseconds)
See Logout Configuration for detailed information.
7.11.3. Platform UI Themes
The Platform UI Configuration allows for the customization of attributes of all pages within DDF. It contains settings to display messages to users at login or in banners in the headers and footers of all pages, along with changing the colors of text and backgrounds.
7.11.3.1. Navigating to UI Theme Configuration
-
Navigate to the Admin Console.
-
Select the Platform application.
-
Select Configuration.
-
Select Platform UI Configuration.
7.11.3.2. Customizing the UI Theme
The customization of the UI theme across DDF is available through the capabilities of Platform UI Configuration. The banner has four items to configure:
-
Header (text)
-
Footer (text)
-
Text Color
-
Background Color
See the Platform UI for all possible configurations of the Platform UI Configuration.
7.12. Miscellaneous Configurations
The optional configurations in this section cover minor changes that can be made to optimize DDF.
7.12.1. Configuring Thread Pools
The org.codice.ddf.system.threadPoolSize
property can be used to specify the size of thread pools used by:
-
Federating requests between DDF systems
-
Downloading resources
-
Handling asynchronous queries, such as queries from the UI
By default, this value is set to 128. It is not recommended to set this value extremely high. If unsure, leave this setting at its default value of 128.
7.12.2. Configuring Jetty ThreadPool Settings
To prevent resource shortages in the event of concurrent requests, DDF allows configuring Jetty ThreadPool settings to specify the minimum and maximum available threads.
-
The settings can be changed at
etc/org.ops4j.pax.web.cfg
under Jetty Server ThreadPool Settings. -
Specify the maximum thread amount with
org.ops4j.pax.web.server.maxThreads
-
Specify the minimum thread amount with
org.ops4j.pax.web.server.minThreads
-
Specify the allotted time for a thread to complete with
org.ops4j.pax.web.server.idleTimeout
DDF does not support changing ThreadPool settings from the Command Console or the Admin Console.
7.12.3. Configuring Alerts
By default, DDF uses two services provided by Karaf Decanter for alerts that can be configured by configuration file. Further information on Karaf Decanter services and configurations can be found here .
7.12.3.1. Configuring Decanter Service Level Agreement (SLA) Checker
The Decanter SLA Checker provides a way to create alerts based on configurable conditions in events posted to decanter/collect/*
and can be configured by editing the file <DDF_HOME>/etc/org.apache.karaf.decanter.sla.checker.cfg
.
By default there are only two checks that will produce alerts, and they are based on the SystemNotice
event property of priority
.
Property | Alert Level | Expression | Description |
---|---|---|---|
priority |
warn |
equal:1,2,4 |
Produce a warn level alert if priority is important (3) |
priority |
error |
equal:1,2,3 |
Produce an error level alert if priority is critical (4) |
7.12.3.2. Configuring Decanter Scheduler
The Decanter Scheduler looks up services implementing the Runnable interface with the service-property decanter.collector.name
and executes the Runnable periodically.
The Scheduler can be configured by editing the file <DDF_HOME>/etc/org.apache.karaf.decanter.scheduler.simple.cfg
.
Property Name | Description | Default Value |
---|---|---|
period |
Decanter simple scheduler period (milliseconds) |
300000 (5 minutes) |
threadIdleTimeout |
The time to wait before stopping an idle thread (milliseconds) |
60000 (1 minute) |
threadInitCount |
Initial number of threads created by the scheduler |
5 |
threadMaxCount |
Maximum number of threads created by the scheduler |
200 |
7.12.4. Encrypting Passwords
DDF includes an encryption service to encrypt plain text such as passwords.
7.12.4.1. Encryption Command
An encrypt security command is provided with DDF to encrypt text. This is useful when displaying password fields to users.
Below is an example of the security:encrypt
command used to encrypt the plain text myPasswordToEncrypt
.
-
Navigate to the Command Console.
security:encrypt Command Exampleddf@local>security:encrypt myPasswordToEncrypt
-
The output is the encrypted value.
security:encrypt Command Outputddf@local>bR9mJpDVo8bTRwqGwIFxHJ5yFJzatKwjXjIo/8USWm8=
8. Running
Find directions here for running an installation of DDF.
- Starting
-
Getting an instance of DDF up and running.
- Managing Services
-
Running DDF as a managed service.
- Maintaining
-
Keeping DDF running with useful tasks.
- Monitoring
-
Tracking system health and usage.
- Troubleshooting
-
Common tips for unexpected behavior.
8.1. Starting
8.1.1. Run DDF as a Managed Service
8.1.1.1. Running as a Service with Automatic Start on System Boot
Because DDF is built on top of Apache Karaf, DDF can use the Karaf Wrapper to run DDF as a service and enable automatic startup and shutdown.
When DDF is started using Karaf Wrapper, new wrapper.log
and wrapper.log.n
(where n goes from 1 to 5 by default) log files will be generated to include wrapper and console specific information.
Warning
|
When installing as a service on *NIX, do not use spaces in the path for <DDF_HOME> as the service scripts that are generated by the wrapper cannot handle spaces. |
Warning
|
Ensure that JAVA_HOME is properly set before beginning this process. See Java Requirements |
-
Create the service wrapper.
DDF can create native scripts and executable files to run itself as an operating system service. This is an optional feature that is not installed by default. To install the service wrapper feature, go the DDF console and enter the command:
ddf@local> feature:install -r wrapper
-
Generate the script, configuration, and executable files:
*NIXddf@local> wrapper:install -i setenv-wrapper.conf -n ddf -d ddf -D "DDF Service"
Windowsddf@local> wrapper:install -i setenv-windows-wrapper.conf -n ddf -d ddf -D "DDF Service"
-
(Windows users skip this step) (All *NIX) If DDF was installed to run as a non-root user (as-recommended,) edit
<DDF_HOME>/bin/ddf-service
and change the property#RUN_AS_USER=
to:<DDF_HOME>/bin/ddf-serviceRUN_AS_USER=<ddf-user>
where <ddf-user> is the intended username:
-
(Windows users skip down) (All *NIX) Edit
<DDF_HOME>/bin/ddf-service
. AddLimitNOFILE
to the [Service] section.<DDF_HOME>/bin/ddf.serviceLimitNOFILE=6815744
-
(Windows users skip this step) (*NIX with
systemd
) Install the wrapper startup/shutdown scripts.Install the service and start it when the system boots, use
systemctl
From an OS console, execute:root@localhost# systemctl enable <DDF_HOME>/bin/ddf.service
-
(Windows users skip this step) (*NIX without
systemd
) Install the wrapper startup/shutdown scripts.If the system does not use
systemd
, use theinit.d
system to install and configure the service. Execute these commands as root or superuser:root@localhost# ln -s <DDF_HOME>/bin/ddf-service /etc/init.d/ root@localhost# chkconfig ddf-service --add root@localhost# chkconfig ddf-service on
-
(Windows only, if the system’s
JAVA_HOME
variable has spaces in it) Edit<DDF_HOME>/etc/ddf-wrapper.conf
. Put quotes aroundwrapper.java.additional.n
system properties for n from 1 to 13 like so:<DDF_HOME>/etc/ddf-wrapper.confwrapper.java.additional.1=-Djava.endorsed.dirs="%JAVA_HOME%/jre/lib/endorsed;%JAVA_HOME%/lib/endorsed;%KARAF_HOME%/lib/endorsed" wrapper.java.additional.2=-Djava.ext.dirs="%JAVA_HOME%/jre/lib/ext;%JAVA_HOME%/lib/ext;%KARAF_HOME%/lib/ext" wrapper.java.additional.3=-Dkaraf.instances="%KARAF_HOME%/instances" wrapper.java.additional.4=-Dkaraf.home="%KARAF_HOME%" wrapper.java.additional.5=-Dkaraf.base="%KARAF_BASE%" wrapper.java.additional.6=-Dkaraf.data="%KARAF_DATA%" wrapper.java.additional.7=-Dkaraf.etc="%KARAF_ETC%" wrapper.java.additional.8=-Dkaraf.log="%KARAF_LOG%" wrapper.java.additional.9=-Dkaraf.restart.jvm.supported=true wrapper.java.additional.10=-Djava.io.tmpdir="%KARAF_DATA%/tmp" wrapper.java.additional.11=-Djava.util.logging.config.file="%KARAF_ETC%/java.util.logging.properties" wrapper.java.additional.12=-Dcom.sun.management.jmxremote wrapper.java.additional.13=-Dkaraf.startLocalConsole=false wrapper.java.additional.14=-Dkaraf.startRemoteShell=true
-
(Windows only) Install the wrapper startup/shutdown scripts.
Run the following command in a console window. The command must be run with elevated permissions.
<DDF_HOME>\bin\ddf-service.bat install
Startup and shutdown settings can then be managed through Services → MMC Start → Control Panel → Administrative Tools → Services.
8.1.1.2. Karaf Documentation
Because DDF is built on top of Apache Karaf, more information on operating DDF can be found in the Karaf documentation .
8.2. Managed Services
The lifecycle of DDF and Solr processes can be managed by the operating system. The DDF documentation provides instructions to install DDF as a managed services on supported unix platforms. However, the documentation cannot account for all possible configurations. Please consult the documentation for the operating system and its init manager if the instructions in this document are inadequate.
8.2.1. Run Solr as Managed Service
These instructions are for configuring Solr as a service managed by the operating system.
8.2.1.1. Configure Solr as a Windows Service
Windows users can use the Task Scheduler to start Solr as a background process.
-
If DDF is running, stop it.
-
Edit
<DDF_HOME>/etc/custom.system.properties
and setstart.solr=false
. This prevents the DDF scripts from attempting to manage Solr’s lifecycle. -
Start the Windows Task Scheduler and open the Task Scheduler Library.
-
Under the Actions pane, select Create Basic Task….
-
Provide a useful name and description, then select Next.
-
Select When the computer starts as the Trigger and select Next.
-
Select Start a program as the Action and select Next.
-
Select the script to start Solr:
<DDF_HOME>\bin\ddfsolr.bat
-
Add the argument
start
in the window pane and select Next. -
Review the settings and select Finish.
It may be necessary to update the Security Options under the task Properties to Run with highest privileges or setting user to "SYSTEM".
Additionally, the process can be set to restart if it fails. The option can be found in the the Properties > Settings tab.
Depending on the system it may also make sense to delay the process from starting for a few minutes until the machine has fully booted. Open the task’s Properties settings and
-
Select Triggers.
-
Select Edit.
-
Select Advanced Settings.
-
Select Delay Task.
8.2.1.2. Configure Solr as a Systemd Service
These instructions are for unix operating systems running the systemd init manager. If configuring a Windows system, see Configure Solr as a Windows Service
-
If DDF is running, stop it.
-
Edit
<DDF_HOME>/etc/custom.system.properties
and setstart.solr=false
. -
Edit the file
<DDF_HOME>/solr/services/solr.service
-
Edit the property
Environment=JAVA_HOME
and replace<JAVA_HOME>
with the absolute path to the directory where the Java Runtime Environment is installed. -
Edit the property
ExecStart
and replace <DDF_HOME> with the absolute path to theddfsolr
file. -
Edit the property
ExecStop
and replace <DDF_HOME> with the absolute path to theddfsolr
file. -
Edit the property
User
and replace<USER>
with the user ID of the Solr process owner.
-
-
From the operating system command line, enable a Solr service using a provided configuration file. Use the full path to the file.
systemctl enable <DDF_HOME>/solr/service/solr.service
-
Start the service.
systemctl start solr
-
Check the status of Solr
systemctl status solr
Solr will start automatically each time the system is booted.
Follow the below steps to start and stop DDF.
8.2.2. Starting from Startup Scripts
Run one of the start scripts from a command shell to start the distribution and open a local console:
<DDF_HOME>/bin/ddf
<DDF_HOME>/bin/ddf.bat
8.2.3. Starting as a Background Process
Alternatively, to run DDF as a background process, run the start
script:
<DDF_HOME>/bin/start
<DDF_HOME>/bin/start.bat
Note
|
If console access is needed while running as a service, run the *NIX
<DDF_HOME>/bin/client Windows
<DDF_HOME>/bin/client.bat -h <FQDN> Use the |
8.2.4. Stopping DDF
There are two options to stop a running instance:
-
Call shutdown from the console:
ddf@local>shutdown
ddf@local>shutdown -f
-
Keyboard shortcut for shutdown
-
Ctrl
-D
-
Cmd
-D
-
-
Or run the stop script:
<DDF_HOME>/bin/stop
<DDF_HOME>/bin/stop.bat
Important
|
Shut Down
Do not shut down by closing the window (Windows, Unix) or using the |
8.3. Maintaining
8.3.1. Console Commands
Once the distribution has started, administrators will have access to a powerful command line console, the Command Console. This Command Console can be used to manage services, install new features, and manage the state of the system.
The Command Console is available to the user when the distribution is started manually or may also be accessed by using the bin/client.bat
or bin/client
scripts.
Note
|
The majority of functionality and information available on the Admin Console is also available on the Command Line Console. |
8.3.1.1. Console Command Help
For details on any command, type help
then the command.
For example, help search
(see results of this command in the example below).
ddf@local>help search DESCRIPTION catalog:search Searches records in the catalog provider. SYNTAX catalog:search [options] SEARCH_PHRASE [NUMBER_OF_ITEMS] ARGUMENTS SEARCH_PHRASE Phrase to query the catalog provider. NUMBER_OF_ITEMS Number of maximum records to display. (defaults to -1) OPTIONS --help Display this help message case-sensitive, -c Makes the search case sensitive -p, -provider Interacts with the provider directly instead of the framework.
The help
command provides a description of the provided command, along with the syntax in how to use it, arguments it accepts, and available options.
8.3.1.2. CQL Syntax
The CQL syntax used with console commands should follow the OGC CQL format. GeoServer provides a description of the grammar and examples in this CQL Tutorial .
Finding all notifications that were sent due to a download:
ddf@local>store:list --cql "application='Downloads'" --type notification
Deleting a specific notification:
ddf@local>store:delete --cql "id='fdc150b157754138a997fe7143a98cfa'" --type notification
8.3.1.3. Available Console Commands
Many console commands are available, including DDF commands and the core Karaf console commands. For more information about these core Karaf commands and using the console, see the Commands documentation for Karaf 4.2.6 at Karaf documentation .
For a complete list of all available commands, from the Command Console, press TAB and confirm when prompted.
Console commands follow a format of namespace:command
.
To get a list of commands, type in the namespace of the desired extension then press TAB.
For example, type catalog
, then press TAB.
8.3.1.3.1. Catalog Commands
Warning
|
Most commands can bypass the Catalog framework and interact directly with the Catalog provider if given the |
Command | Description | ||
---|---|---|---|
|
Provides a basic description of the Catalog implementation. |
||
|
Exports metacards from the local Catalog. Does not remove them. See date filtering options below. |
||
|
Provides a list of environment variables. |
||
|
Exports metacards, history, and their associated resources from the current Catalog. |
||
|
Imports Metacards and history into the current Catalog. |
||
|
Ingests data files into the Catalog. XML is the default transformer used. See Ingest Command for detailed instructions on ingesting data and Input Transformers for all available transformers. |
||
|
Provides the various fields of a metacard for inspection. |
||
|
Retrieves the latest records from the Catalog based on the Core.METACARD_MODIFIED date. |
||
|
Allows two |
||
|
Searches by the given range arguments (exclusively). |
||
|
Deletes a record from the local Catalog. |
||
|
Attempts to delete all records from the local Catalog. |
||
|
Replicates data from a federated source into the local Catalog. |
||
|
Searches records in the local Catalog. |
||
|
Searches spatially the local Catalog. |
||
|
Provides information on available transformers. |
||
|
Validates an XML file against all installed validators and prints out human readable errors and warnings. |
The catalog:dump
command provides selective export of metacards based on date ranges.
The --created-after
and --created-before
options allow filtering on the date and time that the metacard was created, while --modified-after
and --modified-before
options allow filtering on the date and time that the metacard was last modified (which is the created date if no other modifications were made).
These date ranges are exclusive (i.e., if the date and time match exactly, the metacard will not be included).
The date filtering options (--created-after
, --created-before
, --modified-after
, and --modified-before
) can be used in any combination, with the export result including only metacards that match all of the provided conditions.
If no date filtering options are provided, created and modified dates are ignored, so that all metacards match.
Supported dates are taken from the common subset of ISO8601, matching the datetime from the following syntax:
datetime = time | date-opt-time time = 'T' time-element [offset] date-opt-time = date-element ['T' [time-element] [offset]] date-element = std-date-element | ord-date-element | week-date-element std-date-element = yyyy ['-' MM ['-' dd]] ord-date-element = yyyy ['-' DDD] week-date-element = xxxx '-W' ww ['-' e] time-element = HH [minute-element] | [fraction] minute-element = ':' mm [second-element] | [fraction] second-element = ':' ss [fraction] fraction = ('.' | ',') digit+ offset = 'Z' | (('+' | '-') HH [':' mm [':' ss [('.' | ',') SSS]]]
ddf@local>// Given we've ingested a few metacards ddf@local>catalog:latest # ID Modified Date Title 1 a6e9ae09c792438e92a3c9d7452a449f 2020-04-02 2 b4aced45103a400da42f3b319e58c3ed 2020-04-02 3 a63ab22361e14cee9970f5284e8eb4e0 2020-04-02 myTitle ddf@local>// Filter out older files ddf@local>catalog:dump --created-after 2020-04-02 /home/user/ddf-catalog-dump 1 file(s) dumped in 0.015 seconds ddf@local>// Filter out new file ddf@local>catalog:dump --created-before 2020-04-02 /home/user/ddf-catalog-dump 2 file(s) dumped in 0.023 seconds ddf@local>// Choose middle file ddf@local>catalog:dump --created-after 2020-04-02 /home/user/ddf-catalog-dump 1 file(s) dumped in 0.020 seconds ddf@local>// Modified dates work the same way ddf@local>catalog:dump --modified-after 2020-04-02 /home/user/ddf-catalog-dump 1 file(s) dumped in 0.015 seconds ddf@local>// Can mix and match, most restrictive limits apply ddf@local>catalog:dump --modified-after 2020-04-02 /home/user/ddf-catalog-dump 1 file(s) dumped in 0.024 seconds ddf@local>// Can use UTC instead of (or in combination with) explicit time zone offset ddf@local>catalog:dump --modified-after 2020-04-02 /home/user/ddf-catalog-dump 2 file(s) dumped in 0.020 seconds ddf@local>catalog:dump --modified-after 2020-04-02 /home/user/ddf-catalog-dump 1 file(s) dumped in 0.015 seconds ddf@local>// Can leave off time zone, but default (local time on server) may not match what you expect! ddf@local>catalog:dump --modified-after 2020-04-02 /home/user/ddf-catalog-dump 1 file(s) dumped in 0.018 seconds ddf@local>// Can leave off trailing minutes / seconds ddf@local>catalog:dump --modified-after 2020-04-02 /home/user/ddf-catalog-dump 2 file(s) dumped in 0.024 seconds ddf@local>// Can use year and day number ddf@local>catalog:dump --modified-after 2020-04-02 /home/user/ddf-catalog-dump 2 file(s) dumped in 0.027 seconds
8.3.1.3.2. Solr Commands
8.3.1.3.3. Subscriptions Commands
Note
|
The subscriptions commands are installed when the Catalog application is installed. |
Note that no arguments are required for the subscriptions:list
command.
If no argument is provided, all subscriptions will be listed.
A count of the subscriptions found matching the list command’s search phrase (or LDAP filter) is displayed first followed by each subscription’s ID.
ddf@local>subscriptions:list
Total subscriptions found: 3
Subscription ID
my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
my.contextual.id.v30|http://172.18.14.169:8088/mockEventConsumerBinding?WSDL
my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
ddf@local>subscriptions:list "my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL"
Total subscriptions found: 1
Subscription ID
my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
Warning
|
It is recommended to always quote the search phrase (or LDAP filter) argument to the command so that any special characters are properly processed. |
ddf@local>subscriptions:list "my*"
Total subscriptions found: 3
Subscription ID
my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
my.contextual.id.v30|http://172.18.14.169:8088/mockEventConsumerBinding?WSDL
my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
ddf@local>subscriptions:list "*json*"
Total subscriptions found: 1
Subscription ID
my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
ddf@local>subscriptions:list "*WSDL"
Total subscriptions found: 2
Subscription ID
my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
my.contextual.id.v30|http://172.18.14.169:8088/mockEventConsumerBinding?WSDL
The example below illustrates searching for any subscription that has "json" or "v20" anywhere in its subscription ID.
ddf@local>subscriptions:list -f "(|(subscription-id=*json*) (subscription-id=*v20*))"
Total subscriptions found: 2
Subscription ID
my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
The example below illustrates searching for any subscription that has json
and 172.18.14.169
in its subscription ID. This could be a handy way of finding all subscriptions for a specific site.
ddf@local>subscriptions:list -f "(&(subscription-id=*json*) (subscription-id=*172.18.14.169*))" Total subscriptions found: 1 Subscription ID my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
The arguments for the subscriptions:delete
command are the same as for the list
command, except that a search phrase or LDAP filter must be specified.
If one of these is not specified an error will be displayed.
When the delete
command is executed it will display each subscription ID it is deleting.
If a subscription matches the search phrase but cannot be deleted, a message in red will be displayed with the ID.
After all matching subscriptions are processed, a summary line is displayed indicating how many subscriptions were deleted out of how many matching subscriptions were found.
ddf@local>subscriptions:delete "my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification"
Deleted subscription for ID = my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
Deleted 1 subscriptions out of 1 subscriptions found.
ddf@local>subscriptions:delete "my*"
Deleted subscription for ID = my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
Deleted subscription for ID = my.contextual.id.v30|http://172.18.14.169:8088/mockEventConsumerBinding?WSDL
Deleted 2 subscriptions out of 2 subscriptions found.
ddf@local>subscriptions:delete "*json*"
Deleted subscription for ID = my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
Deleted 1 subscriptions out of 1 subscriptions found.
ddf@local>subscriptions:delete *
Deleted subscription for ID = my.contextual.id.v30|http://172.18.14.169:8088/mockEventConsumerBinding?WSDL
Deleted subscription for ID = my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
Deleted subscription for ID = my.contextual.id.json|http://172.18.14.169:8088/services/json/local/event/notification
Deleted 3 subscriptions out of 3 subscriptions found.
ddf@local>subscriptions:delete -f "(&(subscription-id=*WSDL) (subscription-id=*172.18.14.169*))"
Deleted subscription for ID = my.contextual.id.v20|http://172.18.14.169:8088/mockCatalogEventConsumerBinding?WSDL
Deleted subscription for ID = my.contextual.id.v30|http://172.18.14.169:8088/mockEventConsumerBinding?WSDL
Deleted 2 subscriptions out of 2 subscriptions found.
8.3.1.3.4. Platform Commands
Command | Description |
---|---|
|
Shows the current platform configuration. |
|
Provides a list of environment variables. |
8.3.1.3.5. Migrate Commands
Note
|
Performing a data migration creates, updates, or deletes existing metacards within the system. A data migration needs to be run when the structure of the data changes to ensure that existing resources function as expected. The effects of this command cannot be reverted or undone. It is highly recommended to back up the catalog before performing a data migration. |
The syntax for the migration command is
-
migrate:data --list
-
migrate:data --all
-
migrate:data <serviceId>
Select the <serviceId>
based on which data migration task you wish to run.
To see a list of all data migrations tasks that are currently available, run the
migrate:data --list
command.
The --all
option runs every data migration task that is available.
The --list
option lists all available data migration tasks.
Note
|
If an error occurrs performing a data migration the specifics of that error are available in the logs or are printed to the karaf console. |
8.3.1.3.6. Persistence Store Commands
8.3.1.4. Command Scheduler
The Command Scheduler allows administrators to schedule Command Line Commands to be run at specified intervals.
The Command Scheduler allows administrators to schedule Command Line Shell Commands to be run in a platform-independent way. For instance, if an administrator wanted to use the Catalog commands to export all records of a Catalog to a directory, the administrator could write a cron job or a scheduled task to remote into the container and execute the command. Writing these types of scripts are specific to the administrator’s operating system and also requires extra logic for error handling if the container is up. The administrator can also create a Command Schedule, which currently requires only two fields. The Command Scheduler only runs when the container is running, so there is no need to verify if the container is up. In addition, when the container is restarted, the commands are rescheduled and executed again. A command will be repeatedly executed indefinitely according to the configured interval until the container is shutdown or the Scheduled Command is deleted.
Note
|
There will be further attempts to execute the command according to the configured interval even if an attempt fails. See the log for details about failures. |
8.3.1.4.1. Schedule a Command
Configure the Command Scheduler to execute a command at specific intervals.
-
Navigate to the Admin Console (https://{FQDN}:{PORT}/admin).
-
Select the Platform application.
-
Click on the Configuration tab.
-
Select Platform Command Scheduler.
-
Enter the command or commands to be executed in the Command text field. Commands can be separated by a semicolon and will execute in order from left to right.
-
Enter an interval in the Interval field. This can either be a Quartz Cron expression or a positive integer (seconds) (e.x.
0 0 0 1/1 * ? *
or12
). -
Select the interval type in the Interval Type drop-down.
-
Click the Save changes button.
Note
|
Scheduling commands will be delayed by 1 minute to allow time for bundles to load when DDF is starting up. |
8.3.1.4.2. Updating a Scheduled Command
Change the timing, order, or execution of scheduled commands.
-
Navigate to the Admin Console.
-
Click on the Platform application.
-
Click on the Configuration tab.
-
Under the Platform Command Scheduler configuration are all of the scheduled commands. Scheduled commands have the following syntax:
ddf.platform.scheduler.Command.{GUID}
such asddf.platform.scheduler.Command.4d60c917-003a-42e8-9367-1da0f822ca6e
. -
Find the desired configuration to modify, and update fields.
-
Click the Save changes button.
8.3.1.4.3. Output of Scheduled Commands
Commands that normally write out to the console will write out to the log.
For example, if an echo "Hello World"
command is set to run every five seconds, the log contains the following:
16:01:32,582 | INFO | heduler_Worker-1 | ddf.platform.scheduler.CommandJob 68 | platform-scheduler | Executing command [echo Hello World] 16:01:32,583 | INFO | heduler_Worker-1 | ddf.platform.scheduler.CommandJob 70 | platform-scheduler | Execution Output: Hello World 16:01:37,581 | INFO | heduler_Worker-4 | ddf.platform.scheduler.CommandJob 68 | platform-scheduler | Executing command [echo Hello World] 16:01:37,582 | INFO | heduler_Worker-4 | ddf.platform.scheduler.CommandJob 70 | platform-scheduler | Execution Output: Hello World
In short, administrators can view the status of a run within the log as long as INFO was set as the status level.
8.4. Monitoring
The DDF contains many tools to monitor system functionality, usage, and overall system health.
8.4.1. Metrics Reporting
Metrics are available in several formats and levels of detail.
Complete the following procedure now that several queries have been executed.
-
Select Platform
-
Select Metrics tab
-
For individual metrics, choose the format desired from the desired timeframe column:
-
PNG
-
CSV
-
XLS
-
-
For a detailed report of all metrics, at the bottom of the page are selectors to choose time frame and summary level. A report is generated in xls format.
8.4.2. Managing Logging
The DDF supports a dynamic and customizable logging system including log level, log format, log output destinations, roll over, etc.
8.4.2.1. Configuring Logging
Edit the configuration file <DDF_HOME>/etc/org.ops4j.pax.logging.cfg]
8.4.2.2. DDF log file
The name and location of the log file can be changed with the following setting:
log4j.appender.out.file=<DDF_HOME>/data/log/ddf.log
8.4.2.3. Controlling log level
A useful way to debug and detect issues is to change the log level:
log4j.rootLogger=DEBUG, out, osgi:VmLogAppender
8.4.2.4. Controlling the size of the log file
Set the maximum size of the log file before it is rolled over by editing the value of this setting:
log4j.appender.out.maxFileSize=20MB
8.4.2.5. Number of backup log files to keep
Adjust the number of backup files to keep by editing the value of this setting:
log4j.appender.out.maxBackupIndex=10
8.4.2.6. Enabling logging of inbound and outbound SOAP messages for the DDF SOAP endpoints
By default, the DDF start scripts include a system property enabling logging of inbound and outbound SOAP messages.
-Dcom.sun.xml.ws.transport.http.HttpAdapter.dump=true
In order to see the messages in the log, one must set the logging level for org.apache.cxf.services
to INFO
. By default, the logging level for org.apache.cxf
is set to WARN
.
ddf@local>log:set INFO org.apache.cxf.services
8.4.2.7. Logging External Resources
Other appenders can be selected and configured.
For more detail on configuring the log file and what is logged to the console see: Karaf Documentation: Log .
8.4.2.8. Enabling HTTP Access Logging
To enable access logs for the current DDF, do the following:
-
Update the
jetty.xml
file located inetc/
adding the following xml:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<Get name="handler">
<Call name="addHandler">
<Arg>
<New class="org.eclipse.jetty.server.handler.RequestLogHandler">
<Set name="requestLog">
<New id="RequestLogImpl" class="org.eclipse.jetty.server.NCSARequestLog">
<Arg><SystemProperty name="jetty.logs" default="data/log/"/>/yyyy_mm_dd.request.log</Arg>
<Set name="retainDays">90</Set>
<Set name="append">true</Set>
<Set name="extended">false</Set>
<Set name="LogTimeZone">GMT</Set>
</New>
</Set>
</New>
</Arg>
</Call>
</Get>
Change the location of the logs to the desired location. In the settings above, location will default to data/log (same place where the log is located).
The log is using National Center for Supercomputing Association Applications (NCSA) or Common format (hence the class 'NCSARequestLog'). This is the most popular format for access logs and can be parsed by many web server analytics tools. Here is a sample output:
127.0.0.1 - - [14/Jan/2013:16:21:24 +0000] "GET /favicon.ico HTTP/1.1" 200 0
127.0.0.1 - - [14/Jan/2013:16:21:33 +0000] "GET /services/ HTTP/1.1" 200 0
127.0.0.1 - - [14/Jan/2013:16:21:33 +0000] "GET /services//?stylesheet=1 HTTP/1.1" 200 0
127.0.0.1 - - [14/Jan/2013:16:21:33 +0000] "GET /favicon.ico HTTP/1.1" 200 0
8.4.2.9. Using the LogViewer
-
Navigate to the Admin Console
-
Navigate to the System tab
-
Select Logs
The LogViewer displays the most recent 500 log messages by default, but will grow to a maximum of 5000 messages. To view incoming logs, select the PAUSED button to toggle it to LIVE mode. Switching this back to PAUSED will prevent any new logs from being displayed in the LogViewer. Note that this only affects the logs displayed by the LogViewer and does not affect the underlying log.
Log events can be filtered by:
-
Log level (
ERROR
,WARNING
, etc).-
The LogViewer will display at the currently configured log level for the Karaf logs.
-
See Controlling Log Level to change log level.
-
-
-
Log message text.
-
Bundle generating the message.
Warning
|
It is not recommended to use the LogViewer if the system logger is set to a low reporting level such as The actual logs being polled by the LogViewer can still be accessed at |
Note
|
The LogViewer settings don’t change any of the underlying logging settings, only which messages are displayed. It does not affect the logs generated or events captured by the system logger. |
8.5. Troubleshooting
If, after configuration, a DDF is not performing as expected, consult this table of common fixes and workarounds.
Issue | Solution |
---|---|
Unable to unzip distribution on Windows platform |
The default Windows zip utility is not compatible with the DDF distribution zip file. Use Java or a third-party zip utility. |
Unable to federate on Windows Platform |
Windows default firewall is not compatible with DDF. |
Ingesting more than 200,000 data files stored NFS shares may cause Java Heap Space error (Linux-only issue). |
This is an NFS bug where it creates duplicate entries for some files when doing a file list. Depending on the OS, some Linux machines can handle the bug better and able get a list of files but get an incorrect number of files. Others would have a Java Heap Space error because there are too many file to list. As a workaround, ingest files in batches smaller than 200,000. |
Ingesting serialized data file with scientific notation in WKT string causes RuntimeException. |
WKT string with scientific notation such as POINT (-34.8932113039107 -4.77974239601E-5) won’t ingest. This occurs with serialized data format only. |
Exception Starting DDF (Windows) An exception is sometimes thrown starting DDF on a Windows machine (x86). If using an unsupported terminal, |
Install missing Windows libraries. Some Windows platforms are missing libraries that are required by DDF. These libraries are provided by the Microsoft Visual C++ 2008 Redistributable Package x64 . |
CXF BusException The following exception is thrown:
|
Restart DDF.
. Shut down DDF: |
Distribution Will Not Start DDF will not start when calling the start script defined during installation. |
Complete the following procedure.
|
Multiple This can be caused when another DDF is not properly shut down. |
Perform one or all of the following recommended solutions, as necessary.
|
8.5.1. Deleted Records Are Being Displayed In The Search UI’s Search Results
When queries are issued by the Search UI, the query results that are returned are also cached in an internal Solr database for faster retrieval when the same query may be issued in the future. As records are deleted from the catalog provider, this Solr cache is kept in sync by also deleting the same records from the cache if they exist.
Sometimes the cache may get out of sync with the catalog provider such that records that should have been deleted are not.
When this occurs, users of the Search UI may see stale results since these records that should have been deleted are being returned from the cache.
Records in the cache can be manually deleted using the URL commands listed below from a browser.
In these command URLs, metacard_cache
is the name of the Solr query cache.
-
To delete all of the records in the Solr cache:
https://{FQDN}:{PORT}/solr/metacard_cache/update?stream.body=<delete><query>*:*</query></delete>&commit=true
-
To delete a specific record in the Solr cache by ID (specified by the original_id_txt field):
https://{FQDN}:{PORT}/solr/metacard_cache/update?stream.body=<delete><query>original_id_txt:50ffd32b21254c8a90c15fccfb98f139</query></delete>&commit=true
-
To delete record(s) in the Solr cache using a query on a field in the record(s) - in this example, the
title_txt
field is being used with wildcards to search for any records with word remote in the title:
https://{FQDN}:{PORT}/solr/metacard_cache/update?stream.body=<delete><query>title_txt:*remote*</query></delete>&commit=true
9. Data Management
9.1. Ingesting Data
Ingesting is the process of getting metacard(s) into the Catalog Framework. Ingested files are "transformed" into a neutral format that can be searched against as well as migrated to other formats and systems. There are multiple methods available for ingesting files into the DDF.
Note
|
Guest Claims Attributes and Ingest
Ensure that appropriate Guest Claims are configured to allow guest users to ingest data and query the catalog. |
9.1.1. Ingest Command
The Command Console has a command-line option for ingesting data.
Note
|
Ingesting with the console ingest command creates a metacard in the catalog, but does not copy the resource to the content store. The Ingest Command requires read access to the directory being ingested. See the URL Resource Reader for configuring read permission entries to the directory. |
The syntax for the ingest command is
ingest -t <transformer type> <file path>
Select the <transformer type>
based on the type of file(s) ingested.
Metadata will be extracted if it exists in a format compatible with the transformer.
The default transformer is the XML input transformer, which supports the metadata schema catalog:metacard
.
To see a list of all transformers currently installed, and the file types supported by each, run the catalog:transformers
command.
For more information on the schemas and file types(mime-types) supported by each transformer see the Input Transformers.
The <file path>
is relative to the <DDF_HOME> directory.
This can be the path to a file or a directory containing the desired files.
Note
|
Windows Users
On Windows, put the file path in quotes: |
Successful command line ingest operations are accompanied with messaging indicating how many files were ingested and how long the operations took.
The ingest command also prints which files could not be ingested with additional details recorded in the ingest log.
The default location of the log is <DDF_HOME>/data/log/ingest_error.log
.
9.1.2. User Interface Ingest
Files can also be ingested directly from Intrigue.
Warning
|
The Intrigue uploader is intended for the upload of products (such as images or documents), not metadata files (such as Metacard XML). A user will not be able to specify which input transformer is used to ingest the document. |
See Ingesting from Intrigue for details.
9.1.3. Content Directory Monitor Ingest
The Catalog application contains a Content Directory Monitor feature that allows files placed in a single directory to be monitored and ingested automatically. For more information about configuring a directory to be monitored, see Configuring the Content Directory Monitor.
Files placed in the monitored directory will be ingested automatically.
If a file cannot be ingested, they will be moved to an automatically-created directory named .errors
.
More information about the ingest operations can be found in the ingest log.
The default location of the log is <DDF_HOME>/data/log/ingest_error.log
.
Optionally, ingested files can be automatically moved to a directory called .ingested
.
9.1.4. External Methods of Ingesting Data
Third-party tools, such as cURL.exe and the Chrome Advanced Rest Client , can be used to send files to DDF for ingest.
curl -H "Content-type: application/json;id=geojson" -i -X POST -d @"C:\path\to\geojson_valid.json" https://{FQDN}:{PORT}/services/catalog
curl -H "Content-type: application/json;id=geojson" -i -X POST -d @geojson_valid.json https://{FQDN}:{PORT}/services/catalog
Where:
-H adds an HTTP header. In this case, Content-type header application/json;id=geojson
is added to match the data being sent in the request.
-i requests that HTTP headers are displayed in the response.
-X specifies the type of HTTP operation. For this example, it is necessary to POST (ingest) data to the server.
-d specifies the data sent in the POST request. The @
character is necessary to specify that the data is a file.
The last parameter is the URL of the server that will receive the data.
This should return a response similar to the following (the actual catalog ID in the id and Location URL fields will be different):
1
2
3
4
5
6
HTTP/1.1 201 Created
Content-Length: 0
Date: Mon, 22 Apr 2015 22:02:22 GMT
id: 44dc84da101c4f9d9f751e38d9c4d97b
Location: https://{FQDN}:{PORT}/services/catalog/44dc84da101c4f9d9f751e38d9c4d97b
Server: Jetty(7.5.4.v20111024)
-
Use a web browser to verify a file was successfully ingested. Enter the URL returned in the response’s HTTP header in a web browser. For instance in our example, it was
/services/catalog/44dc84da101c4f9d9f751e38d9c4d97b
. The browser will display the catalog entry as XML in the browser. -
Verify the catalog entry exists by executing a query via the OpenSearch endpoint.
-
Enter the following URL in a browser
/services/catalog/query?q=ddf
. A single result, in Atom format, should be returned.
A resource can also be ingested with metacard metadata associated with it using the multipart/mixed content type.
curl -k -X POST -i -H "Content-Type: multipart/mixed" -F parse.resource=@/path/to/resource -F parse.metadata=@/path/to/metacard https://{FQDN}:{PORT}/services/catalog
More information about the ingest operations can be found in the ingest log.
The default location of the log is <DDF_HOME>/data/log/ingest_error.log
.
9.1.5. Creating And Managing System Search Forms Through Karaf
System search provide a way to execute queries with pre-defined templates and search criteria. System search forms are loaded via the system and are read-only. This command allows an administrator to ingest, modify or remove system search forms within the system.
forms:load
forms:load --formsDirectory "/etc/forms" --forms "forms.json" --results "results.json"
Where:
-formsDirectory Specifies the directory in which the forms JSON and XML will reside
-results Specifies the file name of the results.json
file
-forms Specifies the file name of the forms.json
file
It’s important to note that forms:load
will fallback to the system default location for forms, results and the forms directory. The defaults are as follows:
formsDirectory: "/etc/forms"
forms: "forms.json"
results: "results.json"
Example search forms and result form data can be found in <DDF_HOME>/etc/forms/readme.md
.
Managing Forms
In addition to ingesting new system forms into the system, we provide the capability to manage the forms, view the forms and remove them.
forms:manage --list
forms:manage --remove-single "METACARD_ID"
forms:manage --remove-all
Where:
-list Displays the titles and IDs of all system forms in the system
-remove-single Takes in a metacard ID as an argument and removes it
-remove-all Removes all system forms from the system
9.1.6. Other Methods of Ingesting Data
The DDF provides endpoints for integration with other data systems and to further automate ingesting data into the catalog. See Endpoints for more information.
9.2. Validating Data
Configure DDF to perform validation on ingested documents to verify the integrity of the metadata brought into the catalog.
Isolate metacards with data validation issues and edit the metacard to correct validation errors. Additional attributes can be added to metacards as needed.
9.2.1. Validator Plugins on Ingest
When Enforce Errors is enabled within the Admin Console, validator plugins ensure the data being ingested is valid. Below is a list of the validators run against the data ingested.
Note
|
Enforcing errors:
|
9.2.1.1. Validators run on ingest
-
TDF Schema Validation Service: This service validates a TDO against a TDF schema.
-
Size Validator: Validates the size of an attribute’s value(s).
-
Range Validator: Validates an attribute’s value(s) against an inclusive numeric range.
-
Enumeration Validator: Validates an attribute’s value(s) against a set of acceptable values.
-
Future Date Validator: Validates an attribute’s value(s) against the current date and time, validating that they are in the future.
-
Past Date Validator: Validates an attribute’s value(s) against the current date and time, validating that they are in the past.
-
ISO3 Country Code Validator: Validates an attribute’s value(s) against the ISO_3166-1 Alpha3 country codes.
-
Pattern Evaluator: Validates an attribute’s value(s) against a regular expression.
-
Required Attributes Metacard Validator: Validates that a metacard contains certain attributes.
-
Duplication Validator: Validates metacard against the local catalog for duplicates based on configurable attributes.
-
Relationship Validator: Validates values that an attribute must have, can only have, and/or can’t have.
-
Metacard WKT Validator: Validates a location metacard attribute (WKT string) against valid geometric shapes.
9.2.2. Configuring Schematron Services
DDF uses Schematron Validation to validate metadata ingested into the catalog.
Custom schematron rulesets can be used to validate metacard metadata.
Multiple services can be created, and each service can have multiple rulesets associated with it.
Namespaces are used to distinguish services.
The root schematron files may be placed anywhere on the file system as long as they are configured with an absolute path.
Any root schematron files with a relative path are assumed to be relative to <DDF_HOME>/schematron
.
Tip
|
Schematron files may reference other schematron files using an include statement with a relative path. However, when using the document function within a schematron ruleset to reference another file, the path must be absolute or relative to the DDF installation home directory. |
Schematron validation services are configured with a namespace and one or more schematron rulesets. Additionally, warnings may be suppressed so that only errors are reported.
To create a new service:
-
Navigate to the Admin Console.
-
Select the Catalog.
-
Select Configuration.
-
Ensure that
catalog-schematron-plugin
is started. -
Select Schematron Validation Services.
9.2.3. Viewing Invalid Metacards
To view invalid metacards, query for them through Intrigue. Viewing will require DDF-administrator privileges, if Catalog Federation Strategy is configured to filter invalid metacards.
-
Navigate to Intrigue (https://{FQDN}:{PORT}/search).
-
Select Advanced Search.
-
Change the search property to metacard-tags.
-
Change the value of the property to invalid.
-
Select Search.
9.2.4. Manually Editing Attributes
For small numbers of metacards, or for metacards ingested without overrides, attributes can be edited directly.
Warning
|
Metacards retrieved from connected sources or from a fanout proxy will appear to be editable but are not truly local so changes will not be saved. |
-
Navigate to Intrigue.
-
Search for the metacard(s) to be updated.
-
Select the metacards to be updated from the results list.
-
Select Summary or Details.
-
Select Actions from the Details view.
-
Select Add.
-
Select attribute from the list of available attributes.
-
Add any values desired for the attribute.
9.2.5. Injecting Attributes
To create a new attribute, it must be injected into the metacard before it is available to edit or override.
Injections are defined in a JSON-formatted file See Developing Attribute Injections for details on creating an attribute injection file.
9.2.6. Overriding Attributes
Automatically change the value of an existing attribute on ingest by setting an attribute override.
Note
|
Attribute overrides are available for the following ingest methods:
|
-
Navigate to the Admin Console.
-
Select the Catalog application.
-
Select Configuration.
-
Select the configuration for the desired ingest method.
-
Catalog Content Directory Monitor.
-
Confluence Connected Source.
-
Confluence Federated Source.
-
-
Select Attribute Overrides.
-
Enter the key-value pair for the attribute to override and the value(s) to set.
9.3. Backing Up the Catalog
To backup local catalog records, a Catalog Backup Plugin is available. It is not installed by default for performance reasons.
See Catalog Backup Plugin for installation and configuration instructions).
9.4. Removing Expired Records from the Catalog
DDF has many ways to remove expired records from the underlying Catalog data store. Nevertheless, the benefits of data standardization is that an attempt can be made to remove records without the need to know any vendor-specific information. Whether the data store is a search server, a No-SQL database, or a relational database, expired records can be removed universally using the Catalog API and the Catalog Commands.
9.5. Migrating Data
Data migration is the process of moving metacards from one catalog provider to another. It is also the process of translating metadata from one format to another. Data migration is necessary when a user decides to use metadata from one catalog provider in another catalog provider.
The process for changing catalog providers involves first exporting the metadata from the original catalog provider and ingesting it into another.
From the Command Console, use these commands to export data from the existing catalog and then import into the new one.
catalog:export
-
Exports metacards, history, and their associated resources from the current Catalog to an auto-generated file inside <DDF_HOME>.
Use thecatalog:export --help
command to see all available options. catalog:import <FILE_NAME>
-
Imports Metacards and history into the current Catalog.
Use thecatalog:import --help
command to see all available options.
9.6. Automatically Added Metacard Attributes
This section describes how attributes are automatically added to metacards.
9.6.1. Attributes Added on Ingest
A metacard is first created and populated by parsing the ingested resource with an Input Transformer.
Then Attributes Are Injected, Default Attribute Types are applied, and Attribute are Overridden.
Finally the metacard is passed through a series of Pre-Authorization Plugins and Pre-Ingest Plugins.
9.6.1.1. Attributes Added by Input Transformers
Input Transformers create and populate metacards by parsing a resource. See File Format Specific Attributes to see the attributes used for specific file formats.
DDF chooses which input transformer to use by:
-
Resolving the mimetype for the resource.
-
Gathering all of the input transformers associated with the resolved mimetype. See Supported File Formats for a list of supported mimetypes.
-
Iterating through the transformers until a successful transformation is performed.
The first transformer that can successfully create a metacard from the ingested resource is chosen. If no transformer can successfully transform the resource, the ingest process fails.
Important
|
Each of the ingest methods have their own subtle differences when resolving the resource’s mimetype/input transformer. |
9.6.1.2. Attributes Added by Attribute Injection
Attribute Injection is the act of adding attributes to a metacard’s Metacard Type.
A Metacard Type indicates the attributes available for a particular metacard, and is created at the same time as the metacard.
Note
|
Attribute values can only be set/modified if the attribute exists in the metacard’s metacard type. Attributes are initially injected with blank values. However, if an attempt is made to inject an attribute that already exists, the attribute will retain the original value. |
See Catalog Taxonomy Definitions for a list of attributes injected by default.
See Developing Attribute Injections to learn how to configure attribute injections.
9.6.1.3. Attributes Added by Default Attribute Types
Developing Default Attribute Types is a configurable way to assign default values to a metacard’s attributes.
Note that the attribute must be part of the metacard’s Metacard Type before it can be assigned a default value.
See Attributes Added By Attribute Injection for more information about injecting attributes into the metacard type.
9.6.1.4. Attributes Added by Attribute Overrides (Ingest)
Attribute Overriding is the act of replacing existing attribute values with a new value.
Attribute overrides can be configured for the Content Directory Monitor.
Note that the attribute must be part of the metacard’s Metacard Type before it can be overridden.
See Attributes Added By Attribute Injection for more information about injecting attributes into the metacard type.
9.6.1.5. Attributes Added by Pre-Authorization Plugins
The Pre-Authorization Plugins provide an opportunity to take action before any security rules are applied.
-
The Metacard Ingest Network Plugin is a configurable plugin that allows the conditional insertion of new attributes on metacards during ingest based on network information from the ingest request. See Configuring the Metacard Ingest Network Plugin for configuration details.
9.6.1.6. Attributes Added by Pre-Ingest Plugins
The Pre-Ingest Plugins are responsible for setting attribute fields on metacards before they are stored in the catalog.
-
The Expiration Date Pre-Ingest Plugin adds or updates expiration dates which can be used later for archiving old data.
-
The Geocoder Plugin is responsible for populating the metacard’s
Location.COUNTRY_CODE
attribute if the metacard has an associated location. If the metacard’s country code is already populated, the plugin will not override it. -
The Identification Plugin assigns IDs to registry metacards and adds/updates IDs on create and update.
-
The Metacard Groomer plugin adds/updates IDs and timestamps to the created metacard.
9.6.2. Attributes Added on Query
Metacards resulting from a query will undergo Attribute Injection, then have their Attributes Overridden.
9.6.2.1. Attributes Added by Attribute Overrides (Query)
Attribute Overriding is the act of replacing existing attribute values with a new value.
Attribute overrides can be configured for query results from the following Sources:
Note that the attribute must be part of the metacard’s Metacard Type before it can be overridden.
See Attributes Added By Attribute Injection for more information about injecting attributes into the metacard type.
10. Using Intrigue
Intrigue represents the most advanced search interface available with DDF. It provides metadata search and discovery, resource retrieval, and workspace management with a 3D or optional 2D map visualization.
Note
|
Contextual Help Feature
For more detail on any feature or button within Intrigue, click the |
- Advanced Query Builder
-
Search tool for building complex queries beyond basic searches.
- Associations
-
User-defined relationships between different data products.
- Attribute Editor
-
Tool used to edit metadata attributes on uploads.
- Basic Search Tool
-
Search tool for building simple searches.
- Inspector
-
Tool for viewing and editing metadata attributes.
- Lists
-
User-defined collections of related results or products.
- Map Tools Widget
-
Tool for customizing or navigating the map view.
- Metadata Quality
-
A measure of the completeness or correctness of the metadata of a product.
- Result Forms
-
Customizable templates of the attributes shown when viewing searches.
- Search Forms
-
Customizable templates of the attributes used in creating searches.
- Sources View
-
View the health and status of all configured data sources
- Temporal Search
-
Basic search using time-based search terms.
- Spatial Search
-
Basic search using location-based search terms.
- Text Search
-
Basic search using the text of documents and/or metadata.
- Visuals
-
Tools to view search results or the information about them.
- Workspaces
-
User-defined collections of searches and search settings.
10.1. Accessing Intrigue
The default URL for Intrigue is https://{FQDN}:{PORT}/search/catalog
Note
|
Catalog UI Guest Users
If Guest access has been enabled, users not signed in to DDF (i.e. guest users) will have access to search functions, but all workspace configuration and settings will only exist locally and will not be available for sharing. |
Intrigue defaults to the Search view. For other views, select the Navigation menu in the upper-left corner of Intrigue and select the desired view.
10.2. Searching Intrigue
The Search pane has two tabs: Search and Lists.
10.2.1. Creating a Search
Search queries are grouped together into Workspaces. These searches can be saved, edited, and duplicated as the basis of further searches.
-
From the main Intrigue screen, select Search Intrigue.
-
From the dialog that opens, select the edit icon to name the search if it will be reused or shared.
-
Select the type of search to perform: Text, Basic, or Advanced.
-
-
Results will be displayed in the Search Tab.
-
If too many or too few results are returned, edit the search parameters by selecting the edit icon.
-
Once the search is correct, select the Save icon next to the workspace name in the top bar.
-
Select the navigation menu icon.
-
Select Workspaces.
-
Enter search terms into the Search box.
-
A new workspace, by default called New Workspace, will be created containing only the new search.
-
Rename the workspace, if desired.
-
Select the Save icon next to the workspace name.
-
Text: Perform a minimal textual search that is treated identically to a Basic search with only Text specified.
-
Basic: Define a Text, Temporal, Spatial, or Type Search.
-
Text Search Details: Searches across all textual data of the targeted data source. Text search capabilities include:
-
Search for an exact word, such as
Text = apple
: Returns items containing the word "apple" but not "apples". Matching occurs on word boundaries. -
Search for the existence of items containing multiple words, such as
Text = apple orange
: Returns items containing both "apple" and "orange" words. Words can occur anywhere in an item’s metadata. -
Search using wildcards, such as
Text = foo*
: Returns items containing words like "food", "fool", etc.. -
Wildcards should only be used for single word searches, not for phrases.
WarningWhen searching with wildcards, do not include the punctuation at the beginning or the end of a word. For example, search for Text = ca*
instead ofText = -ca*
when searching for words like "cat", "-cat", etc.. and search forText = *og
instead ofText = *og.
when searching for words like "dog", "dog.", etc.. -
Text searches are by default case insensitive, but case sensitive searches are an option.
-
-
Temporal Search Details: Search based on absolute time of the created, modified, or effective date.
-
Any: Search without any time restrictions (default).
-
After: Search records after a specified time.
-
Before: Search records before a specified time.
-
Between: Set a beginning and end time to search between.
-
Relative: Search records relative to the current time.
-
-
-
Search by latitude/longitude (decimal degrees or degrees minutes seconds), USNG/MGRS, or UTM
-
Search by entering a Keyword for a region, country, or city in the Location section of the query builder.
-
To search using a line, polygon, point-radius, or bounding box, select the shape to draw, then select Draw.
NoteIntersecting Polygon SearchsIf a self intersecting polygon is used to perform a geographic search, the polygon will be converted into a non-intersection one via a convex hull conversion. In the example below the blue line shows the original self intersecting search polygon and the red line shows the converted polygon that will be used for the search. The blue dot shows a search result that was not within the original polygon but was returned because it was within the converted polygon.
-
-