From 8cd7c806f359ff7a9364466ad4ee13a8c4983b6b Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Fri, 10 Oct 2025 15:51:25 -0600 Subject: [PATCH 1/6] Organize NCSS reference docs under 'services' --- .../src/site/_data/sidebars/user_sidebar.yml | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml index 1b2f8e0299..9205df5862 100644 --- a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml +++ b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml @@ -301,9 +301,13 @@ entries: url: /dataset_source_plugin.html output: web, pdf - - title: Netcdf Subset Service (NCSS) + - title: Services output: web, pdf subfolderitems: + - title: TDS Services + url: /services_ref.html + output: web, pdf + - title: NCSS Reference url: /netcdf_subset_service_ref.html output: web, pdf @@ -316,13 +320,6 @@ entries: url: /ncss_point.html output: web, pdf - - title: Services - output: web, pdf - subfolderitems: - - title: TDS Services - url: /services_ref.html - output: web, pdf - - title: WCS Reference url: /wcs_ref.html output: web, pdf From 2fe738fc87b8a5f98886cc35d48014a473eb88cd Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Fri, 10 Oct 2025 15:52:02 -0600 Subject: [PATCH 2/6] Add link to WMS palette converter to upgrade docs --- .../src/site/pages/tds_tutorial/production/Upgrade.md | 4 +++- .../src/site/pages/tds_tutorial/production/Upgrade.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md b/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md index 9227dbd866..4310f97f7b 100644 --- a/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md +++ b/docs/quickstart/src/site/pages/tds_tutorial/production/Upgrade.md @@ -1,6 +1,6 @@ --- title: Upgrading to TDS version 5 -last_updated: 2025-09-17 +last_updated: 2025-10-10 sidebar: quickstart_sidebar toc: false permalink: upgrade.html @@ -179,6 +179,8 @@ TDS 5.x uses the [edal-java](https://github.com/Reading-eScience-Centre/edal-jav As this is a major version change to that library, there may be some breaking changes. See also the [edal user guide](https://reading-escience-centre.gitbooks.io/edal-user-guide/content/) and the [changes from ncWMS 1.x](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/01-ncwms1x.html#changes). +If you created palette files for TDS 4.x and would like to use them in TDS 5.x, an open source tool named [Magic Palette Converter](https://github.com/billyz313/magic-palette-converter){:target="_blank"} for THREDDS is available to assist in the conversion (special thanks to [Billy Ashmall](https://github.com/Unidata/tds/discussions/346){:target="_blank"}!) + Starting with TDS 5.6, `wmsConfig.xml` has been extended to support four new default options: * defaultAboveMaxColor * defaultBelowMinColor diff --git a/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md b/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md index 4a54463f5c..542d482f19 100644 --- a/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md +++ b/docs/userguide/src/site/pages/tds_tutorial/production/Upgrade.md @@ -1,6 +1,6 @@ --- title: Upgrading to TDS version 5 -last_updated: 2025-09-17 +last_updated: 2025-10-10 sidebar: user_sidebar toc: false permalink: upgrade.html @@ -178,6 +178,8 @@ TDS 5.x uses the [edal-java](https://github.com/Reading-eScience-Centre/edal-jav As this is a major version change to that library, there may be some breaking changes. See also the [edal user guide](https://reading-escience-centre.gitbooks.io/edal-user-guide/content/) and the [changes from ncWMS 1.x](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/01-ncwms1x.html#changes). +If you created palette files for TDS 4.x and would like to use them in TDS 5.x, an open source tool named [Magic Palette Converter](https://github.com/billyz313/magic-palette-converter){:target="_blank"} for THREDDS is available to assist in the conversion (special thanks to [Billy Ashmall](https://github.com/Unidata/tds/discussions/346){:target="_blank"}!) + Starting with TDS 5.6, `wmsConfig.xml` has been extended to support four new default options: * defaultAboveMaxColor * defaultBelowMinColor From 2eb60e743db5d2e1b9b6435c20641cd14bb5c425 Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Fri, 10 Oct 2025 15:56:27 -0600 Subject: [PATCH 3/6] Organize GRIB reference docs --- .../src/site/_data/sidebars/user_sidebar.yml | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml index 9205df5862..349af2353a 100644 --- a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml +++ b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml @@ -331,6 +331,16 @@ entries: - title: Customizing WMS url: /customizing_wms.html output: web, pdf + - title: GRIB + output: web, pdf + subfolderitems: + - title: GRIB Collection Configuration + url: /grib_collection_config_ref.html + output: web, pdf + + - title: GRIB Time Partitions + url: /partitions_ref.html + output: web, pdf - title: Configuring TDS With DatasetScan url: /tds_dataset_scan_ref.html @@ -356,22 +366,10 @@ entries: url: /tdm_ref.html output: web, pdf - - - title: PointFeature Collection Reference url: /pointfeature_collection_ref.html output: web, pdf - - title: GRIB Collection Configuration - url: /grib_collection_config_ref.html - output: web, pdf - - - title: GRIB Time Partitions - url: /partitions_ref.html - output: web, pdf - - - - title: Digital Libraries Reference url: /digital_libraries.html output: web, pdf \ No newline at end of file From f9ffc48be6194ada875005ce41f839c1cafad4be Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Fri, 10 Oct 2025 16:08:33 -0600 Subject: [PATCH 4/6] more userguide sidebar reorg --- .../src/site/_data/sidebars/user_sidebar.yml | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml index 349af2353a..91f4a6f4b4 100644 --- a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml +++ b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml @@ -268,28 +268,20 @@ entries: output: web, pdf folderitems: - - title: Dataset Viewer - url: /viewers_ref.html - output: web, pdf - - + - output: web, pdf subfolders: - - title: TDS Catalogs + - title: THREDDS Catalogs output: web, pdf subfolderitems: - - title: TDS Config (threddsConfig.xml) - url: /tds_config_ref.html + - title: Client-Side Catalog Specification + url: /client_side_catalog_specification.html output: web, pdf - title: Server-Side Catalog Specification url: /server_side_catalog_specification.html output: web, pdf - - title: Client-Side Catalog Specification - url: /client_side_catalog_specification.html - output: web, pdf - - title: For Developers output: web, pdf subfolderitems: @@ -342,6 +334,10 @@ entries: url: /partitions_ref.html output: web, pdf + - title: TDS Config (threddsConfig.xml) + url: /tds_config_ref.html + output: web, pdf + - title: Configuring TDS With DatasetScan url: /tds_dataset_scan_ref.html output: web, pdf @@ -366,6 +362,10 @@ entries: url: /tdm_ref.html output: web, pdf + - title: Dataset Viewer + url: /viewers_ref.html + output: web, pdf + - title: PointFeature Collection Reference url: /pointfeature_collection_ref.html output: web, pdf From fb30eb931fef61df6d972053c576d5b9da7570e0 Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Fri, 10 Oct 2025 16:08:51 -0600 Subject: [PATCH 5/6] Formatting/layout updates for threddsConfig.xml ref docs --- docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md | 6 +++--- docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md | 6 +++--- docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md b/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md index 2c75653e40..f31f7fafd7 100644 --- a/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md +++ b/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md @@ -1,8 +1,8 @@ --- -title: TDS Configuration File Reference (`threddsConfig.xml`) -last_updated: 2024-11-26 +title: TDS Configuration File Reference (threddsConfig.xml) +last_updated: 2025-10-10 sidebar: admin_sidebar -toc: true +toc: false permalink: tds_config_ref.html --- diff --git a/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md b/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md index 17c83f641b..a5d46ea390 100644 --- a/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md +++ b/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md @@ -1,8 +1,8 @@ --- -title: TDS Configuration File Reference (`threddsConfig.xml`) -last_updated: 2024-11-26 +title: TDS Configuration File Reference (threddsConfig.xml) +last_updated: 2025-10-10 sidebar: quickstart_sidebar -toc: true +toc: false permalink: tds_config_ref.html --- diff --git a/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md b/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md index 19adee727d..9cdd53b473 100644 --- a/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md +++ b/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md @@ -1,8 +1,8 @@ --- -title: TDS Configuration File Reference (`threddsConfig.xml`) -last_updated: 2024-11-26 +title: TDS Configuration File Reference (threddsConfig.xml) +last_updated: 2025-10-10 sidebar: user_sidebar -toc: true +toc: false permalink: tds_config_ref.html --- From 5ceacd1dff7d6d46a4ba8f3586868bd9b18d1028 Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Fri, 10 Oct 2025 16:16:22 -0600 Subject: [PATCH 6/6] Favor newer TLS docs in quickstart guide --- .../production/EnableTLSEncryption.md | 262 ------------------ .../production}/TLSEncryption.md | 0 2 files changed, 262 deletions(-) delete mode 100644 docs/quickstart/src/site/pages/tds_tutorial/production/EnableTLSEncryption.md rename docs/quickstart/src/site/pages/{ => tds_tutorial/production}/TLSEncryption.md (100%) diff --git a/docs/quickstart/src/site/pages/tds_tutorial/production/EnableTLSEncryption.md b/docs/quickstart/src/site/pages/tds_tutorial/production/EnableTLSEncryption.md deleted file mode 100644 index 912a2d2a87..0000000000 --- a/docs/quickstart/src/site/pages/tds_tutorial/production/EnableTLSEncryption.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: Enable TLS/SSL Encryption -last_updated: 2020-08-24 -sidebar: quickstart_sidebar -toc: false -permalink: enable_tls_encryption.html ---- - -This section demonstrates how to enable TLS/SSL Encryption for the TDS and Tomcat Servlet Container. - -{%include note.html content=" -This section assumes you have successfully performed the tasks as outlined in the [Getting Started With The TDS](install_java_tomcat.html) section of this tutorial. -" %} - -## Rationale -* Communication between two servers can be intercepted (i.e., an http transaction between client and server). -* An attacker can eavesdrop on the conversation and control the relay of messages between the victims, making them believe that they are talking directly to each other over a private connection. -* The use of digital certificates adds a layer of security by allowing the receiver of the message to verify the sender is who he or she claims to be. -* Any intercepted information that is encrypted also adds a layer of security (the attacker must take the extra step of un-encrypting the data to view the message). -* Transport Layer Security (TLS), and formerly Secure Sockets Layer (SSL), is a cryptographic protocol that provides security and data integrity for communications over TCP/IP networks. -* TLS/SSL allows applications to communicate across a network in a way designed to prevent eavesdropping, tampering, and message forgery. -* TLS/SSL uses a cryptographic system that uses two keys to encrypt data: a public key known to everyone and a private or secret key known only to the recipient of the message. -* By convention, URLs that require an TLS/SSL connection start with `https` instead of `http`. - -{%include note.html content=" -For more information on how TLS/SSL works, Wikipedia details the [steps involved](https://en.wikipedia.org/wiki/Transport_Layer_Security){:target='_blank'} during an TLS/SSL transaction. -" %} - -## TLS/SSL Certificates -* A public key certificate is an electronic document which incorporates a digital signature to bind together a public key with identity information of the certificate user. -* The certificate can be used to verify that a public key belongs to an individual. -* The digital signature can be signed by a Certificate Authority (CA) or the certificate user (a self-signed certificate). - -### Do Not Use Self-Signed Certificates -{%include important.html content=" -Unidata _highly_ recommends the use of a certificate signed by a Certificate Authority (CA). -" %} - -* Browser warnings for self-signed certificates can be very confusing to users and make them question the legitimacy of your web site. -* It's about trust: CA-signed certificates verify your identify to your users. - If the traffic between your server and the client is intercepted, an attacker can inject their own self-signed cert in the place of yours and the visitor will likely not notice. -* Self-signed certificates cannot (by nature) be revoked, which may allow an attacker who has already gained access to monitor and inject data into a connection to spoof an identity if a private key has been compromised. - CAs on the other hand have the ability to revoke a compromised certificate, which prevents its further use. - -### Certificate `keystore` File -A keystore file stores the details of the TLS/SSL certificate necessary to make the protocol secured. -The Tomcat documentation includes a section on [importing your certificate](https://tomcat.apache.org/tomcat-{{ site.tomcat_version }}-doc/ssl-howto.html#Prepare_the_Certificate_Keystore){:target="_blank"} into a keystore file. -Tomcat uses the keystore file for TLS/SSL transactions. - -## Enabling TLS/SSL In Tomcat - -The following example demonstrates enabling TLS/SSL in the Tomcat Servlet Container on a linux system as the `root` user. - -{% capture cert %} -This section assumes you have already imported your CA-signed certificate into the [keystore](https://tomcat.apache.org/tomcat-{{ site.tomcat_version }}-doc/ssl-howto.html#Prepare_the_Certificate_Keystore){:target='_blank'} file. -{% endcapture %} -{% include info.html content=cert %} - -1. Modify the Tomcat configuration to enable TLS/SSL: - - Open `${tomcat_home}/conf/server.xml` with your favorite text editor: - - ~~~bash - # vi server.xml - ~~~ - - Locate the `Java HTTP/1.1 Connector` listening on port `8080` and verify it is redirecting TLS/SSL traffic to port `8443`: - ~~~xml - - ~~~ - - Find and uncomment the `NIO implementation SSL HTTP/1.1 Connector` listening on port `8443` to activate this connector: - - ~~~xml - - - - - - ~~~ - - {% capture connector %} - Tomcat also offers a `SSL/TLS HTTP/1.1 Connector` which utilizes `APR/native implementation`. - Consult the [Documentation](http://tomcat.apache.org/tomcat-{{ site.tomcat_version }}-doc/config/http.html){:target='_blank'} to see if you should use this connector in lieu of the `NIO implementation SSL HTTP/1.1` connector. - {% endcapture %} - {% include info.html content=connector %} - - Specify the keystore file in the `certificateKeystoreFile` attribute of the `Certificate` element to tell Tomcat where to find your keystore (the path will be relative to `${tomcat_home}` directory). - - In this example, the keystore file is `${tomcat_home}/conf/tds-keystore`: - - ~~~xml - - - - - - ~~~ - - If you opted to not use the default keystore password (`changeit`), you'll need to specify the new password so Tomcat can open the file. Add the `certificateKeystorePassword` attribute of the `Certificate` element for your keystore password. - - ~~~xml - - - - - - ~~~ - - - {%include important.html content=" - Keep in mind: Changes to `${tomcat_home}/conf/server.xml` do not take effect until Tomcat is restarted. - " %} - -2. Verify TLS/SSL has been enabled. - - Restart Tomcat: - - ~~~bash - # /usr/local/tomcat/bin/shutdown.sh - # /usr/local/tomcat/bin/startup.sh - ~~~ - - Verify Tomcat is listening on port 8443 by running the `netstat` command: - - ~~~bash - # netstat -an | grep tcp | grep 8443 - ~~~ - - `netstat` (short for network statistics) is a command-line tool that displays: - - * network connections (both incoming and outgoing) - * routing tables - * and a number of network interface statistics - - Look for something like the following in the output (output may vary between operating systems): - - ~~~bash - tcp 0 0 0.0.0.0:8443 0.0.0.0:* LISTEN - ~~~ - - {%include note.html content=" - Run `man netstat` in your terminal window to learn more about this command. - " %} - -### Troubleshooting -* Check the XML syntax in `${tomcat_home}/conf/server.xml` to make sure it is well-formed and without error. -* Did you restart Tomcat after you made your changes to `server.xml`? -* Did you specify the full path to the keystore file in `server.xml`? - -{%include ahead.html content=" -Other than the compelling security reasons, you will want to enable TLS/SSL to take advantage of a couple of monitoring and debugging tools: the [TDS Remote Management Tool](remote_management_ref.html), and the [TdsMonitor Tool](using_the_tdsmonitor_tool.html) -- both of which (out-of-the-box) require TLS/SSL to access. -" %} - -## Configuring Web Applications for TLS/SSL - -* The web application deployment descriptor, a.k.a. `web.xml`, specifies if all or parts of it need to be accessed via TLS/SSL. -* Deployment descriptors are found in the `WEB-INF` directory of the web application: `${tomcat_home}/webapps/application_name/WEB-INF/web.xml`. -* By convention, Tomcat and other servlet containers will read the web application deployment descriptors for initialization parameters and container-managed security constraints upon application deployment. -* The TDS has been pre-configured to require that TLS/SSL encryption is enabled in order to access the both the [TDS Remote Management Tool](remote_management_ref.html), and the [TdsMonitor Tool](using_the_tdsmonitor_tool.html). - -This is the entry in the TDS `web.xml` for the TDS Remote Management Tool: - -~~~xml - - - - sensitive read access - /admin/* - - - tdsConfig - - - CONFIDENTIAL - - -~~~ - -* The `` establishes a requirement that the constrained requests be received over a protected transport layer connection. - This guarantees how the data will be transported between client and server. -* `` choices for type of transport guarantee include `NONE`, `INTEGRAL`, and `CONFIDENTIAL`: - 1. Specify `CONFIDENTIAL` when the application requires that data be transmitted so as to prevent other entities from observing the contents of the transmission. (E.g., via TLS/SSL.) - 2. Specify `INTEGRAL` when the application requires that the data be sent between client and server in such a way that it cannot be changed in transit. - 3. Specify `NONE` to indicate that the container must accept the constrained requests on any connection, including an unprotected one. - -{%include note.html content=" - For more information on how to configure security requirements for a web application in a deployment descriptor, see: [Defining Security Requirements for Web Applications](https://javaee.github.io/tutorial/security-webtier.html#BNCAS){:target='_blank'}. -" %} - -## Accessing TDS Monitoring and Debugging Tools -Other than the compelling security reasons, you will want to enable TLS/SSL to take advantage of the [TDS Remote Management Tool](remote_management_ref.html)and the [TdsMonitor Tool](using_the_tdsmonitor_tool.html) monitoring and debugging tools. - -1. Enable TLS/SSL in Tomcat - If Tomcat has not already been configured to run via TLS/SSL, follow the tutorial in the previous section to Enable TLS/SSL in Tomcat. -2. Modify `${tomcat_home}/conf/tomcat-users.xml` to add the new tdsConfig and tdsMonitor roles. - Add these roles to your list of roles: - - ~~~xml - - - - - - - - - ~~~ - - {%include important.html content=" - Keep in mind: Changes to `${tomcat_home}/conf/tomcat-users.xml` do not take effect until Tomcat is restarted. - " %} - -3. Restart Tomcat and access the [TDS Remote Management Tool](http://localhost:8080/thredds/admin/debug){:target="_blank"} in your browser (authenticate with the login/password specified in `${tomcat_home}/conf/tomcat-users.xml`). - - {% include image.html file="tds/tutorial/production_servers/remotemanagementtool.png" alt="TDS Remote Management Tool" caption="" %} - - -## Resources -* [Qualys SSL Server Test](https://www.ssllabs.com/ssltest/){:target="_blank"} - is a free online service that analyzes the configuration of any public TLS/SSL web server. - Note: be sure to check the Do not show the results on the boards box if you do not want your results to be public. -* [TLS/SSL Configuration HOW-TO](https://tomcat.apache.org/tomcat-{{ site.tomcat_version }}-doc/ssl-howto.html){:target="_blank"} - The Apache Tomcat document detailing how to enable TLS/SSL. -* [Tomcat Migration Guide](https://tomcat.apache.org/migration.html){:target="_blank"} - A document detailing the various changes between Tomcat versions. -* [When are self-signed certificates acceptable?](https://www.sslshopper.com/article-when-are-self-signed-certificates-acceptable.html){:target="_blank"} - A compelling argument as to why self-signed certificates should not be used in a production environment diff --git a/docs/quickstart/src/site/pages/TLSEncryption.md b/docs/quickstart/src/site/pages/tds_tutorial/production/TLSEncryption.md similarity index 100% rename from docs/quickstart/src/site/pages/TLSEncryption.md rename to docs/quickstart/src/site/pages/tds_tutorial/production/TLSEncryption.md