diff --git a/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md b/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md index a44f0ae635..0dcd2ac44e 100644 --- a/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md +++ b/docs/adminguide/src/site/pages/thredds/ThreddsConfigRef.md @@ -1,6 +1,6 @@ --- title: TDS Configuration File Reference (`threddsConfig.xml`) -last_updated: 2020-08-24 +last_updated: 2024-11-26 sidebar: admin_sidebar toc: true permalink: tds_config_ref.html @@ -61,7 +61,7 @@ logos of the server and host institution) * all generated THREDDS catalogs that don't override this information -The best way to use your own logo is to put it in the `${tds.content.root.path}/thredds/public/` directory, and specify it in `serverInformation` as `/thredds/`, e.g.: +The best way to use your own logo is to put it in the `${tomcat path}/webapps/thredds/` directory, and specify it in `serverInformation` as `/thredds/`, e.g.: ~~~xml /thredds/yourIcon.gif @@ -201,8 +201,8 @@ The following shows all the configuration options available in the WCS section o true (see the note below) - 15 min - 30 min + 10 min + 5 min ~~~ @@ -235,7 +235,8 @@ The following shows all the configuration options available in the WMS section o true false - /WEB-INF/palettes + wmsPalettes + wmsStyles 2048 2048 @@ -248,8 +249,24 @@ Here is the description of the various options: * `allowRemote`: a value of `true` enables the WMS service for datasets available from a remote server. * `paletteLocationDir`: optionally specify the location of the directory containing your own palette files, by specifying the directory where they are contained. - If the directory location starts with a `/`, the path is absolute, otherwise it is relative to `${tds.content.root.path}/thredds/`. - If you don't specify it, or specify it incorrectly, the default palettes will be used, which are in the war file under `WEB-INF/palettes`. + * If the directory location starts with a `/`, the path is absolute, otherwise it is relative to `${tds.content.root.path}/thredds/`. + * The default directory for custom palette files is `${tds.content.root.path}/thredds/wmsPalettes`. + * If you don't specify a custom palette directory, or specify it incorrectly, the default directory will be used. + * Custom palette files will be loaded in addition to the default palettes, which are described + [here](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/04-usage.html#getmap). + * Note that the palette file format has changed between TDS version 4.x and TDS version 5.x. Please refer to the + [EDAL-Java palette file directory](https://github.com/Reading-eScience-Centre/edal-java/tree/master/graphics/src/main/resources/palettes) + for examples of palette files that are compatible with the TDS version 5.x WMS service. + * More information on the format of palette files can also be found in the + [ncWMS documentation](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/06-development.html#:~:text=To%20add%20new,in%20hexadecimal%20notation.). + * 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"}!) +* `stylesLocationDir`: optionally specify the location of the directory containing your own style files, by specifying the directory + where they are contained. + * If the directory location starts with a `/`, the path is absolute, otherwise it is relative to `${tds.content.root.path}/thredds/`. + * The default directory for custom styles files is `${tds.content.root.path}/thredds/wmsStyles`. + * If you don't specify a custom styles directory, or specify it incorrectly, the default directory will be used. + * More information on the format of style files can also be found in the + [ncWMS documentation](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/06-development.html#styles). * `maxImageWidth`: the maximum image width in pixels that this WMS service will return. * `maxImageHeight`: the maximum image height in pixels that this WMS service will return. @@ -270,9 +287,9 @@ The following shows all the configuration options available in the `NetcdfSubset true (see the note below) - 15 min - 30 min - 300 MB + 10 min + 5 min + -1 ~~~ @@ -290,15 +307,16 @@ Here is the description of the various options: Optional; default is that there is no size limitation. If the file is > 2 GB, large format netCDF will be written. -### ncISO Service +### ncISO Services -By default, these services are enabled, and can be disabled by including the following in the `threddsConfig.xml` file: +By default, these services are disabled. +Provided that you have added the [ncISO plugin](adding_ogc_iso_services.html#nciso-configuration), these services can be enabled by including the following in the `threddsConfig.xml` file: ~~~xml - false - false - false + true + true + true ~~~ @@ -380,7 +398,7 @@ ln -s /data/thredds/content content ~~~ These various caches at times may contain large amounts of data. -You should choose a location that will not fill up (especially if that location affects other important locations like `/opt`, `/home`, etc). +You should choose a location that will not fill up (especially if that location affects other important locations like `/opt`, `/usr/local`, `/home`, etc). If you have a large disk for your data, that may be a good location for the cache directories. On unix-like machines, you can run `df` to get a listing of disks on your machine. The listing includes size and mount location. @@ -419,7 +437,7 @@ We recommend that you use this default, by not specifying the `DiskCache.dir` el ~~~xml - ${tds.content.root.path}/thredds/cache/agg/ + (see the note below) 24 hours 90 days nestedDirectory @@ -431,7 +449,7 @@ If not otherwise set, the TDS will use the `${tds.content.root.path}/thredds/cac We recommend that you use this default, by not specifying a `AggregationCache`.`dir` element. Every `scour` amount of time, any item that hasn't been changed since `maxAge` time will be deleted. -If you have aggregations that never change, set `scour` to `-1` to disable the operation. +If you have aggregations that never change, set `scour` to `-1 sec` to disable the operation. Otherwise, make `maxAge` longer than the longest time between changes. Basically, you don't want to remove active aggregations. @@ -453,9 +471,10 @@ We recommend that you use the default settings, by not specifying this option. ~~~xml - ${tds.content.root.path}/thredds/cache/collection/ + (see the note below) 1000 1 + small ~~~ @@ -471,6 +490,12 @@ We recommend that you use the default settings, by not specifying this option. If it is possible to have more FMRC files than your `maxEntries`, then this value should be increased. It is strongly advised not to configure this value to more than 10, as the cache works progressively slower when the actual size grows far beyond the size configured in your `maxEntries`. See [here](https://gerrit.googlesource.com/modules/cache-chroniclemap/+/HEAD/src/main/resources/Documentation/config.md#configuration-parameters) for more details. +* `averageValueSize`: the average size of the cached value (the grid and variable information), which is used when allocating memory for the cache. + The possible values are `small`, `medium`, or `large`. + The default value is `small`. + In most cases the default value should work fine. However, if your FMRC datasets have hundreds of variables, + and you are experiencing issues with the cache filling up even though you have adjusted the `maxEntries` and `maxBloatFactor`, + then this may need to be increased to `medium`, or in very rare circumstances `large`. ### GRIB Index Redirection @@ -478,7 +503,7 @@ We recommend that you use the default settings, by not specifying this option. false false - ${tds.content.root.path}/thredds/cache/grib/ + (see the note below) nestedDirectory 0 hours 90 days @@ -488,6 +513,7 @@ We recommend that you use the default settings, by not specifying this option. These elements control where GRIB index files are written. * If `alwaysUse` is true, grib index files will always be written to the _index directory_ specified by `dir` (see [choosing a cache directory](#disk-caching-and-temporary-files)). + If not otherwise set, the TDS will use the ${tds.content.root.path}/thredds/cache/grib/ directory If `neverUse` is true, the index directory will never be used. If neither is set, the TDS will try to write grib indexes to the same directory as the original file, and if the TDS doesn't have write permission it will then write the files to the index directory. Write permission will be determined by what rights the _Tomcat user_ has (the user that starts up Tomcat). diff --git a/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md b/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md index dae333b286..fb0eb7268c 100644 --- a/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md +++ b/docs/quickstart/src/site/pages/thredds/ThreddsConfigRef.md @@ -1,6 +1,6 @@ --- title: TDS Configuration File Reference (`threddsConfig.xml`) -last_updated: 2020-08-24 +last_updated: 2024-11-26 sidebar: quickstart_sidebar toc: true permalink: tds_config_ref.html @@ -29,39 +29,39 @@ In the `serverInformation` element, you provide basic information about your ser ~~~xml - Initial TDS Installation - /thredds/threddsIcon.png - Initial TDS Installation - - Scientific Data - meteorology, atmosphere, climate, ocean, earth science - - - Support - My Group - support@my.group - - - - My Group - http://www.my.group/ - myGroup.gif - My Group - + Initial TDS Installation + /thredds/threddsIcon.png + Initial TDS Installation + + Scientific Data + meteorology, atmosphere, climate, ocean, earth science + + + Support + My Group + support@my.group + + + + My Group + http://www.my.group/ + myGroup.gif + My Group + ~~~ The information provided in the `serverInformation` element is used in: * the headers of all generated HTML pages (they contain the names and -logos of the server and host institution) + logos of the server and host institution) * the Server section of the WMS `GetCapabilities` response * the server information documents ([see below](#server-information-documents)) * the Server section of the WCS `GetCapabilities` response * all generated THREDDS catalogs that don't override this information -The best way to use your own logo is to put it in the `${tds.content.root.path}/thredds/public/` directory, and specify it in `serverInformation` as `/thredds/`, e.g.: +The best way to use your own logo is to put it in the `${tomcat path}/webapps/thredds/` directory, and specify it in `serverInformation` as `/thredds/`, e.g.: ~~~xml /thredds/yourIcon.gif @@ -95,7 +95,7 @@ Default CSS files are provided, and should not be modified. Instead, these can b 3. The CSS used in TDS Dataset catalogs pages 4. The CSS used in the OPeNDAP form. 5. Google Analytics Tracking Code (GATC) enables tracking catalog use. - Obtain the GATC from [Google](https://marketingplatform.google.com/about/analytics/){:target="_blank"} and enter it here to enable this feature. + Obtain the GATC from [Google](https://marketingplatform.google.com/about/analytics/){:target="_blank"} and enter it here to enable this feature. 6. If set to `true`, [`schema.org/Dataset`](https://schema.org/Dataset){:target="_blank"} objects will be encoded using json-ld and embedded into the `` element of the generated dataset HTML pages. ### Controlling THREDDS Catalog Output @@ -175,13 +175,13 @@ However, for remote catalogs, these services must be explicitly enabled in `thre ~~~ This controls the `OPeNDAP` data service. -Because it's easy for a user to inadvertently request very large amounts of data, the TDS limits the size of the data response. +Because it's easy for a user to inadvertently request very large amounts of data, the TDS limits the size of the data response. In our experience legitimate requests ask for subset sizes that are well below the defaults. * `ascLimit`: maximum size of an ascii data request , in Megabytes. - Default 50 Mbytes. + Default 50 Mbytes. * `binLimit`: maximum size of a binary data request , in Megabytes. - Default is 500 Mbytes. + Default is 500 Mbytes. * `serverVersion`: this is the String returned by the OPeNDAP `getVersion` request, and placed into the `XDOS-Server` HTTP Header on all OPeNDAP responses. ### WCS Service @@ -201,22 +201,22 @@ The following shows all the configuration options available in the WCS section o true (see the note below) - 15 min - 30 min + 10 min + 5 min ~~~ -We recommend that you include in the `threddsConfig.xml` file only the options you want to change. +We recommend that you include in the `threddsConfig.xml` file only the options you want to change. Here is the description of the various options: * `allow`: a value of `false` disables the WCS service. * `dir`: the working directory where generated files are cached before being sent to the client (see [choosing a -cache directory](#disk-caching-and-temporary-files)). + cache directory](#disk-caching-and-temporary-files)). If not otherwise set, the TDS will use the `${tds.content.root.path}/thredds/cache/wcs/` directory. We recommend that you do not specify a `WCS.dir` element, and use the default. * `scour`: how often to scour the working directory, to delete files that were not successfully downloaded. * `maxAge`: how long to leave the files in the working directory while the download is occurring. - The files are deleted after a successful download. Do not set to <= 0. + The files are deleted after a successful download. Do not set to <= 0. ### WMS Service @@ -235,7 +235,8 @@ The following shows all the configuration options available in the WMS section o true false - /WEB-INF/palettes + wmsPalettes + wmsStyles 2048 2048 @@ -247,9 +248,25 @@ Here is the description of the various options: * `allow`: a value of `false` disables the WMS service. * `allowRemote`: a value of `true` enables the WMS service for datasets available from a remote server. * `paletteLocationDir`: optionally specify the location of the directory containing your own palette files, by specifying the directory -where they are contained. - If the directory location starts with a `/`, the path is absolute, otherwise it is relative to `${tds.content.root.path}/thredds/`. - If you don't specify it, or specify it incorrectly, the default palettes will be used, which are in the war file under `WEB-INF/palettes`. + where they are contained. + * If the directory location starts with a `/`, the path is absolute, otherwise it is relative to `${tds.content.root.path}/thredds/`. + * The default directory for custom palette files is `${tds.content.root.path}/thredds/wmsPalettes`. + * If you don't specify a custom palette directory, or specify it incorrectly, the default directory will be used. + * Custom palette files will be loaded in addition to the default palettes, which are described + [here](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/04-usage.html#getmap). + * Note that the palette file format has changed between TDS version 4.x and TDS version 5.x. Please refer to the + [EDAL-Java palette file directory](https://github.com/Reading-eScience-Centre/edal-java/tree/master/graphics/src/main/resources/palettes) + for examples of palette files that are compatible with the TDS version 5.x WMS service. + * More information on the format of palette files can also be found in the + [ncWMS documentation](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/06-development.html#:~:text=To%20add%20new,in%20hexadecimal%20notation.). + * 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"}!) +* `stylesLocationDir`: optionally specify the location of the directory containing your own style files, by specifying the directory + where they are contained. + * If the directory location starts with a `/`, the path is absolute, otherwise it is relative to `${tds.content.root.path}/thredds/`. + * The default directory for custom styles files is `${tds.content.root.path}/thredds/wmsStyles`. + * If you don't specify a custom styles directory, or specify it incorrectly, the default directory will be used. + * More information on the format of style files can also be found in the + [ncWMS documentation](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/06-development.html#styles). * `maxImageWidth`: the maximum image width in pixels that this WMS service will return. * `maxImageHeight`: the maximum image height in pixels that this WMS service will return. @@ -270,9 +287,9 @@ The following shows all the configuration options available in the `NetcdfSubset true (see the note below) - 15 min - 30 min - 300 MB + 10 min + 5 min + -1 ~~~ @@ -281,7 +298,7 @@ Here is the description of the various options: * `allow`: a value of `false` disables the NetCDF Subset Service. * `dir`: the working directory for creating files for download (see [choosing a cache directory](#disk-caching-and-temporary-files)). - If not otherwise set, the TDS will use the `${tds.content.root.path}/thredds/cache/ncss/` directory. + If not otherwise set, the TDS will use the `${tds.content.root.path}/thredds/cache/ncss/` directory. We recommend that you do not specify a `NetcdfSubsetService.dir` element, and use the default. * `scour`: how often to scour the working directory, to delete files that were not successfully downloaded. * `maxAge`: how long to leave the files in the working directory while the download is occurring. @@ -290,15 +307,16 @@ Here is the description of the various options: Optional; default is that there is no size limitation. If the file is > 2 GB, large format netCDF will be written. -### ncISO Service +### ncISO Services -By default, these services are enabled, and can be disabled by including the following in the `threddsConfig.xml` file: +By default, these services are disabled. +Provided that you have added the [ncISO plugin](adding_ogc_iso_services.html#nciso-configuration), these services can be enabled by including the following in the `threddsConfig.xml` file: ~~~xml - false - false - false + true + true + true ~~~ @@ -379,8 +397,8 @@ cd {tomcat_home} ln -s /data/thredds/content content ~~~ -These various caches at times may contain large amounts of data. -You should choose a location that will not fill up (especially if that location affects other important locations like `/opt`, `/home`, etc). +These various caches at times may contain large amounts of data. +You should choose a location that will not fill up (especially if that location affects other important locations like `/opt`, `/usr/local`, `/home`, etc). If you have a large disk for your data, that may be a good location for the cache directories. On unix-like machines, you can run `df` to get a listing of disks on your machine. The listing includes size and mount location. @@ -405,7 +423,7 @@ If `alwaysUse` is `false`, TDS will try to write them to the same directory as t Write permission will be determined by what rights the _Tomcat user_ has (the user that starts up and runs the Tomcat servlet container). For security reasons, you want to carefully limit the file permissions of the Tomcat user. -When opening a file, if `alwaysUse` is `true`, TDS looks only in the cache directory for the temporary file. +When opening a file, if `alwaysUse` is `true`, TDS looks only in the cache directory for the temporary file. If `alwaysUse` is `false`, TDS wil first look for the temporary file in the same directory as the original file, and if not found, then will look in the cache. Every `scour` amount of time, the largest items in the cache will be deleted, until the directory has less than `maxSize` bytes. @@ -419,24 +437,24 @@ We recommend that you use this default, by not specifying the `DiskCache.dir` el ~~~xml - ${tds.content.root.path}/thredds/cache/agg/ + (see the note below) 24 hours 90 days nestedDirectory ~~~ -If you have `joinExisting` Aggregations, coordinate information will be written to a cache directory specified by `dir` (see [choosing a cache directory](#disk-caching-and-temporary-files)). +If you have `joinExisting` Aggregations, coordinate information will be written to a cache directory specified by `dir` (see [choosing a cache directory](#disk-caching-and-temporary-files)). If not otherwise set, the TDS will use the `${tds.content.root.path}/thredds/cache/agg/` directory. We recommend that you use this default, by not specifying a `AggregationCache`.`dir` element. Every `scour` amount of time, any item that hasn't been changed since `maxAge` time will be deleted. -If you have aggregations that never change, set `scour` to `-1` to disable the operation. +If you have aggregations that never change, set `scour` to `-1 sec` to disable the operation. Otherwise, make `maxAge` longer than the longest time between changes. Basically, you don't want to remove active aggregations. `cachePathPolicy` controls how cache files are stored in `dir`. -It must be set to one of `oneDirectory` or `nestedDirectory` (the default). +It must be set to one of `oneDirectory` or `nestedDirectory` (the default). `oneDirectory` will put all cache files into the same directory, while `nestedDirectory` will preserve their directory structure. Use `nestedDirectory` for large aggregations, as some file systems struggle when a directory contains thousands of files. @@ -453,9 +471,10 @@ We recommend that you use the default settings, by not specifying this option. ~~~xml - ${tds.content.root.path}/thredds/cache/collection/ + (see the note below) 1000 1 + small ~~~ @@ -471,6 +490,12 @@ We recommend that you use the default settings, by not specifying this option. If it is possible to have more FMRC files than your `maxEntries`, then this value should be increased. It is strongly advised not to configure this value to more than 10, as the cache works progressively slower when the actual size grows far beyond the size configured in your `maxEntries`. See [here](https://gerrit.googlesource.com/modules/cache-chroniclemap/+/HEAD/src/main/resources/Documentation/config.md#configuration-parameters) for more details. +* `averageValueSize`: the average size of the cached value (the grid and variable information), which is used when allocating memory for the cache. + The possible values are `small`, `medium`, or `large`. + The default value is `small`. + In most cases the default value should work fine. However, if your FMRC datasets have hundreds of variables, + and you are experiencing issues with the cache filling up even though you have adjusted the `maxEntries` and `maxBloatFactor`, + then this may need to be increased to `medium`, or in very rare circumstances `large`. ### GRIB Index Redirection @@ -478,7 +503,7 @@ We recommend that you use the default settings, by not specifying this option. false false - ${tds.content.root.path}/thredds/cache/grib/ + (see the note below) nestedDirectory 0 hours 90 days @@ -488,13 +513,14 @@ We recommend that you use the default settings, by not specifying this option. These elements control where GRIB index files are written. * If `alwaysUse` is true, grib index files will always be written to the _index directory_ specified by `dir` (see [choosing a cache directory](#disk-caching-and-temporary-files)). - If `neverUse` is true, the index directory will never be used. + If not otherwise set, the TDS will use the ${tds.content.root.path}/thredds/cache/grib/ directory + If `neverUse` is true, the index directory will never be used. If neither is set, the TDS will try to write grib indexes to the same directory as the original file, and if the TDS doesn't have write permission it will then write the files to the index directory. Write permission will be determined by what rights the _Tomcat user_ has (the user that starts up Tomcat). For security reasons, you want to carefully limit the file permissions of the Tomcat user. -* The policy must be set to one of `oneDirectory` or `nestedDirectory` (the default). +* The policy must be set to one of `oneDirectory` or `nestedDirectory` (the default). `oneDirectory` will put all index files into the same directory, while `nestedDirectory` will preserve the directory structure -of the index files. + of the index files. Use `nestedDirectory` for large collections of files, as some file systems struggle when a directory contains thousands of files. * Every `scour` amount of time, any files in the cache that are older than `maxAge` will be removed. To turn off scouring, set the scour time to 0 (e.g.: `0 hours`), or leave out the `` element. @@ -503,7 +529,7 @@ of the index files. Managing the GRIB indices is an important task, and can be difficult if the files are changing, as in a rolling archive, or for very large collections. There are two typical ways to do this: -* For rolling archives, allow the indices to be written in the same directory as the data files by specifying `true` or by not using a `` or `` element (which uses the default behavior). +* For rolling archives, allow the indices to be written in the same directory as the data files by specifying `true` or by not using a `` or `` element (which uses the default behavior). When you delete the data files, delete the corresponding indices. * If you need to keep the index files separate from your data files, set `true`, and use `nestedDirectory`. @@ -569,13 +595,13 @@ The `scour` element uses any valid `udunits` time string, such as `sec, min, hou * `keepInMemory`: Configuration catalogs are always cached in memory, for performance reasons. You can set the maximum number of catalogs in the cache. The amount of memory used by a catalog can be approximated simply by the size in bytes of the `catalog.xml` file itself. -* `reread`: +* `reread`: * `always`: on startup, all catalogs are read. (default). _safest, use if there are a small number of catalogs._ * `check`: on startup, catalogs that have changed will be reread. * `trigger`: after initial read, config catalogs will only be read again if user explicitly triggers it. _fastest startup if catalogs rarely change._ -* `dir`: The location where the database is written. +* `dir`: The location where the database is written. Default is `${tds.content.root.path}/thredds/cache/catalog/`. We recommend that you leave the default and use a symbolic link to move it if needed. * `maxDatasets`: The maximum number of datasets. diff --git a/docs/quickstart/src/site/pages/thredds/WmsRef.md b/docs/quickstart/src/site/pages/thredds/WmsRef.md index b39081a61d..2dca5ac915 100644 --- a/docs/quickstart/src/site/pages/thredds/WmsRef.md +++ b/docs/quickstart/src/site/pages/thredds/WmsRef.md @@ -1,6 +1,6 @@ --- title: TDS Web Map Service (WMS) -last_updated: 2020-08-24 +last_updated: 2020-11-26 sidebar: quickstart_sidebar toc: false permalink: adding_wms.html @@ -43,7 +43,7 @@ Additional WMS configuration options can be set in the `threddsConfig.xml` file. Further WMS configuration properties are set in the wmsConfig.xml file. These properties are mainly related with styling of WMS images. Similar to the `threddsConfig.xml file`, the WMS configuration file (wmsConfig.xml) is found in the `$tds.content.root.path{}/content/thredds` directory. -A detailed description of the wmsConfig.xml file can be found at the MyOcean "Detailed WMS Configuration" page. +A detailed description of the wmsConfig.xml file can be on the [Customizing WMS](../adminguide/customizing_wms.html) reference page. If you are installing a new TDS, you should find a default `wmsConfig.xml` file (along with other configuration files) in your content`/thredds` directory after you first deploy the TDS. If you are upgrading from a TDS version before version `4.2.20100615.*`, you will have to copy the default file from `${tomcat_home}/webapps/thredds/WEB-INF/altContent/startup/wmsConfig.xml`. diff --git a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml index 09977584ca..5187f7a216 100644 --- a/docs/userguide/src/site/_data/sidebars/user_sidebar.yml +++ b/docs/userguide/src/site/_data/sidebars/user_sidebar.yml @@ -331,6 +331,10 @@ entries: url: /adding_wms.html output: web, pdf + - title: Customizing WMS + url: /customizing_wms.html + output: web, pdf + - title: Configuring TDS With DatasetScan url: /tds_dataset_scan_ref.html output: web, pdf diff --git a/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md b/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md index d1ecf776b3..cbcc9b651c 100644 --- a/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md +++ b/docs/userguide/src/site/pages/thredds/ThreddsConfigRef.md @@ -1,6 +1,6 @@ --- title: TDS Configuration File Reference (`threddsConfig.xml`) -last_updated: 2020-08-24 +last_updated: 2024-11-26 sidebar: user_sidebar toc: true permalink: tds_config_ref.html @@ -390,6 +390,12 @@ The various cache directory locations are all under `/{tds.content.root.path}/th We recommend that you use these defaults, by not specifying them in the `threddsConfig.xml` file. If you need to move the cache location, move all of them by using a symbolic file link in `${tds.content.root.path}/thredds/`. +At Unidata, we move the entire content directory by creating a symbolic link: + +~~~bash +cd {tomcat_home} +ln -s /data/thredds/content content +~~~ These various caches at times may contain large amounts of data. You should choose a location that will not fill up (especially if that location affects other important locations like `/opt`, `/usr/local`, `/home`, etc). diff --git a/docs/userguide/src/site/pages/thredds/WmsConfig.md b/docs/userguide/src/site/pages/thredds/WmsConfig.md new file mode 100644 index 0000000000..518b336771 --- /dev/null +++ b/docs/userguide/src/site/pages/thredds/WmsConfig.md @@ -0,0 +1,63 @@ +--- +title: Customizing WMS +last_updated: 2021-08-06 +sidebar: user_sidebar +toc: false +permalink: customizing_wms.html +--- + +Several properties related to the generation of images from the WMS service can be configured using the `wmsConfig.xml` file. +By default, this file is located in the `${tds.content.root.path}/thredds` directory. +An example `wmsConfig.xml` file is shipped with the TDS, which looks like: + +{% capture rmd %}{% includefile ../tds/src/main/webapp/WEB-INF/altContent/startup/wmsConfig.xml %}{% endcapture %} + +~~~xml +{{ rmd }} +~~~ + +This file provides a way to set default values for WMS parameters when they are missing from a request. +In general, you can provide default values for the following properties: + * _allowFeatureInfo_: Allow _GetFeatureInfo_ requests. + * _defaultColorScaleRange_: Range of values to when generating images. + * _defaultPaletteName_: A color palette name (see the [ncWMS User Guide](https://reading-escience-centre.gitbooks.io/ncwms-user-guide/content/04-usage.html#getmap){:target="_blank"} for options). + * _defaultNumColorBands_: The number of colour bands to use. + * _logScaling_: Use a logarithmic scale when generating images. + * _intervalTime_: Deprecated, does not work. + +There are two main elements to the `wmsConfig.xml` file - the ``, and the ``. +Each controls the level of granularity at which default values are chosen. +Settings in `` take precedence over settings in ``. + +## Global + +The `` element contains one `` and one `` child element. +It is within these elements that you can control default settings at a `global` level. + +### Default + +All options must be configured in this section. +These set the default values for all WMS requests. + +### Standard Names + +Values set under `` can be overridden by matching on the value of a `standard_name` attribute of a variable. +With the exception of _allowFeatureInfo_, all other properties can be set based on `standard_name`. +Because this is global, you must include information about the `units` used to define the ``. +This allows the WMS service to deal with variables that have the same `standard_name` yet have different, but comparable, units. +The units must be defined using a `udunits` compatible string. +The current set of unit strings support can be found in [this xml document](https://docs.unidata.ucar.edu/thredds/udunits2/current/udunits2_combined.xml){:target="_blank"}. +A more user-friendly version can be found at [this very helpful site](https://ncics.org/portfolio/other-resources/udunits2/){:target="_blank"}, which is maintained by the [North Carolina Institute for Climate Studies](https://ncics.org/){:target="_blank"}. + +## Overrides + +The `` element contains a series of `` children. +The `pathSpec` attribute of a `` element allows for applying default settings based on the dataset path as seen in the TDS url (i.e. the dataset ID). +Default values can be set for all properties based on the path. +With the exception of _allowFeatureInfo_, these can be overridden on a variable by variable basis based on the name of the variable. + +## Default Precedence Summary + +Default values for a given property are selected based on matches (lowest to highest precedence): + +`global/defaults` < `global/standardName` < `overrides/pathDefaults` < `overrides/variable`