16. Appendix: Metacat Properties

Caution

Before making any changes to Metacat’s properties files, it is highly recommended that you first read Properties Overview, for a detailed overview of how properties are used and updated in Metacat.

In summary:

1. Metacat’s configuration settings are located in two files:

   • metacat.properties: a large, non-editable file, containing the default values for every single property recognized by Metacat, and

   • metacat-site.properties: a smaller, editable file, containing only the values that need to be changed to override the defaults.

2. More-dynamic settings (such as authorization and database connection values) are managed with the Metacat Configuration utility (see Configuring Metacat). Whenever these settings are changed from their defaults, the new values are automatically saved to metacat-site.properties.

3. More-static settings, which cannot be set via the Configuration utility, may also be changed in the metacat-site.properties file, either by editing existing property entries, or by adding them there if they do not already exist. Note that metacat.properties: should not be edited.

The default location for the metacat-site.properties file is /var/metacat/config/metacat-site.properties, but note that this location may have been changed via the Metacat Configuration utility. See Properties Overview for more details.

16.1. Server Properties

All of Metacat’s server properties are managed with the form-based configuration utility, though they can also be accessed directly by editing the metacat-site.properties file. More information on each is included below.

Property	Description	Example
server.name	The network host name used to access Metacat. Note that this is not necessarily the physical name of the server running Metacat. The host name should not include the protocol prefix (http://). Default Value: localhost	knb.ecoinformatics.org
server.port	The network port used to access Metacat for connections. This can be either an https port, such as 443, or an http port, such as 80. Default Value: 443	443
server.https	To indicate the server port is an https one or an http one. True means an https port; false means an http port. Default Value: true	true
server.internalName	The internal network host name used to access Metacat. It is used to improve performance since it bypasses the external network interface to directly access files, e.g. schema and style sheet files located within Metacat itself. The host name should not include the protocol prefix (http://). Default Value: localhost	localhost
server.internalPort	The network port used to access Metacat for the internal server name. This is usually 80 if Apache Web server is running, and 8080 if Tomcat is running alone. Default Value: 80	80

16.2. Application Properties

Metacat’s application properties are described below. Properties that can only be edited manually in the metacat-site.properties file are marked with an asterisk (*). All others are managed with the properties configuration utility.

Property	Description	Example
application.metacatVersion*	The Metacat version number. It is set by the build engineer at build time. Usually, the value should never be changed. Default Value: X.X.X (where X.X.X is the current version of Metacat)	3.0.0
application.metacatReleaseInfo*	Release information for display purposes. Typically the property is set during the release candidate cycle to let users know which candidate they are downloading.	Release Candidate 1
application.envSecretKeys*	See Secret Properties A colon-delimited list of mappings between “secret” properties (e.g. passwords) and environment variables used to pass them to Metacat. Passing secrets to Metacat via environment variables avoids having them in the properties file as plain text.
application.deployDir	The directory where Web applications are deployed. Usually, the value is a directory named “webapps” in the Tomcat installation directory.	/usr/local/tomcat/webapps
application.context	The name of the Metacat application directory in the deployment directory. This corresponds to the first part of the WAR file name (the part before .war). Most commonly, this is “metacat”, but it can be changed to other things.	knb
index.context	The name of the Metacat index webapp in the deployment directory. Most commonly, this is “metacat-index”, but it can be changed if needed.	metacat-index
ui.context	The name of the Metacat UI directory in the deployment directory. Often the UI is deployed as the ROOT webapp, in which case the property should be blank (“”).	metacatui
application.default-style	A custom Metacat Web skin usually associated with an organizational theme. If your organization has no custom skin, leave the value as “default”.	default
application.sitePropertiesDir	The directory in which to store the metacat-site.properties file. The directory should be outside the Metacat installation directories so custom settings will not be lost when Metacat is upgraded. The site properties file directory must be writable by the user that starts Tomcat (and thus Metacat). Default Value: /var/metacat/config	/var/metacat/config
application.datafilepath	The directory in which to store data files. The directory should be outside the Metacat installation directories so data files will not be lost when Metacat is upgraded. The data file directory must be writable by the user that starts Tomcat (and thus Metacat). Default Value: /var/metacat/data	/var/metacat/data
application.inlinedatafilepath	The directory where inline data files will be stored. Inline data files are created from data that is embedded in EML metadata. The directory should be outside the Metacat installation directories so data files will not be lost when Metacat is upgraded. For clarity of data, this should probably not be the same as application.datafilepath. The data file directory must be writable by the user that starts Tomcat (and thus Metacat). Default Value: /var/metacat/inline-data	/var/metacat/inline-data
application.documentfilepath	The directory where metadata files will be stored. The directory should be outside the Metacat installation directories so document files will not be lost when Metacat is upgraded. For clarity of organization, this should probably not be the same as application.datafilepath or application.inlinedatafilepath. The data file directory must be writable by the user that starts Tomcat (and thus Metacat). Default Value: /var/metacat/documents	/var/metacat/documents
application.tempDir	The directory where the Metacat data registry stores temporary files. The directory should not be the same as application.datafilepath or application.inlinedatafilepath (or any other persistent file path)	/var/metacat/temporary
cn.server.publiccert.filename	The location(s) of one or more certificate files containing public keys that will be used to verify incoming request auth (JWT) tokens, in addition to verifying them against the configured CN server. Multiple paths should be delimited by semicolons (;) Default Value: (empty: only cn is used for token verification)
dataone.nodeToken.file	The path to a file that contains an authentication token. This token will be used by the dataone-indexer, to enable indexing of private datasets. Default Value: /var/metacat/certs/token

16.3. Solr Properties

Metacat’s Solr properties are described below. Properties that can only be edited manually in the metacat-site.properties file are marked with an asterisk (*). All others are managed with the properties configuration utility.

Property	Description	Example
solr.baseURL	The URL of the Solr server which Metacat can access.	http://localhost:8983/solr
solr.homeDir	The Solr home directory (not to be confused with the Solr installation directory) is where Solr manages core directories with index files. The directory must be writable by the user that starts the Solr service.	/var/metacat/solr-home2
solr.coreName	The name of the Solr core which holds the index of the Metacat objects.	metacat-index
solr.env.script.path	An environment specific include file overrides defaults used by the bin/solr script. Metacat modifies this file to add the solr.home as the default data directory. This file should be writable by the Tomcat user.	/etc/default/solr.in.sh

16.4. Database Properties

Metacat’s database properties are described next. Properties that can only be edited manually in the metacat-site.properties file are marked with an asterisk (*). All others are managed with the properties configuration utility.

Property	Description	Example
database.connectionURI	The JDBC connection URI for the main database instance of Metacat. The URI is formatted like this: jdbc:<database_type>:thin@<your_server_name>:1521:<metacat_database_name> NOTE: You must create an empty database prior to initial Metacat configuration. Default Value: jdbc:postgresql://localhost/metacat	jdbc:postgresql://yourserver.yourdomain.edu/metacat
database.user	The user for the main database instance of Metacat. The user must have already been created on the database.	metacat-user
database.password	The password of the user for the main database instance of Metacat. The password must have already been created for the user.	securepassword4843
database.type	The type of database you are running. Currently, there are two supported types, Oracle and Postgres. Default Value: postgres	postgres
database.driver	The JDBC driver to be used to access the main database instance of Metacat. There is one driver associated with each type of database. Default Value: org.postgresql.Driver	org.postgresql.Driver
database.adapter	The adapter class that allows Metacat to access your database type. There is one adapter associated with each type of database. Default Value: edu.ucsb.nceas.dbadapter.PostgresqlAdapter	edu.ucsb.nceas.dbadapter.PostgresqlAdapter
database.scriptsuffix.<database_type>	The script suffix tells the system which database scripts to run (postgres or oracle) when installing or updating database schema. Default Values: database.scriptsuffix.postgres=postgres.sql database.scriptsuffix.oracle=oracle.sql	postgres.sql
database.upgradeVersion.<database_version>	Which database scripts to run when updating database schema. There is a database.upgradeVersion entry for every Metacat database schema version. Each schema version corresponds to an application version. Default Values: database.upgradeVersion.0.0.0=xmltables,loaddtdschema database.upgradeVersion.1.2.0=upgrade-db-to-1.2 database.upgradeVersion.1.3.0=upgrade-db-to-1.3 database.upgradeVersion.1.4.0=upgrade-db-to-1.4 database.upgradeVersion.1.5.0=upgrade-db-to-1.5 database.upgradeVersion.1.6.0=upgrade-db-to-1.6 database.upgradeVersion.1.7.0=upgrade-db-to-1.7 database.upgradeVersion.1.8.0=upgrade-db-to-1.8 database.upgradeVersion.1.9.0=upgrade-db-to-1.9 database.upgradeVersion.2.0.0=upgrade-db-to-2.0	upgrade-db-to-1.2
database.initialConnections*	The number of initial connection that Metacat creates to the database. Default Value: 5	5
database.incrementConnections*	The number of connections Metacat creates when it requires more connections. Default Value: 5	5
database.maximumConnections*	The maximum number of database connections Metacat can make. Default Value: 200	25
database.maximumConnectionAge*	The maximum time in milliseconds that a database connection can live. Default Value: 120000	120000
database.maximumConnectionTime*	The maximum time in milliseconds that a database connection can accumulate in actual connection time. Default Value: 60000	60000
database.maximumUsageNumber*	The maximum number of times a single connection can be used. Default Value: 100	100
database.numberOfIndexingThreads*	The number of threads available for indexing. Default Value: 5	5
database.indexingTimerTaskTime*	The time in milliseconds between indexing. Default Value: 604800000	604800000
database.indexingInitialDelay*	The delay in milliseconds before first indexing is executed. Default Value: 3600000	3600000
database.maximumIndexDelay*	The time in milliseconds that an indexing thread will wait when it can’t get a doc id before retrying the indexing. Default Value: 5000	5000
database.runDBConnectionRecycleThread*	Determines whether the database connection pool should run a thread to recycle connections. Possible values are “on” and “off” Default Value: off	off
database.cycleTimeOfDBConnection*	The time in milliseconds between connection recycling runs. Default Value: 30000	30000
database.webResultsetSize*	Determines the number of results that can be returned to a Web browser from a query. Default Value: 7000	7000

16.5. Authorization and Authentication Properties

Metacat’s authorization and authentication properties are described in the table below. Properties that can only be edited manually in the metacat-site.properties file are marked. All others are managed with the properties configuration utility.

Authorization and Authentication Properties

Property	Description	Example
auth.class	The class used for user authentication. Currently, both the AuthFile and AuthLdap classes are included in the Metacat distribution. Note: If you implement another authentication strategy by implementing a Java class that extends the AuthInterface interface and rebuilding Metacat, change this property to the fully qualified class name of your custom authentication mechanism. Default Value: edu.ucsb.nceas.metacat.authentication.AuthFile	edu.ucsb.nceas.metacat.AuthLdap
auth.timeoutMinutes*	The number of minutes that a user will stay logged in to Metacat without any activity. Default Value: 180	180
auth.administrators	A semicolon-separated list of ORCID IDs for users who have administrative Metacat privileges. At least one user must be entered when Metacat is first installed and configured.	https://orcid.org/0000-0001-2345-6789; https://orcid.org/0000-0002-2345-678X
auth.userManagementUrl	A web page provides the user management such as creating a new user and changing password.	https://identity.nceas.ucsb.edu
auth.file.path	The absolute path of the password file which stores the username/password and users’ information. This file is used for the file-based authentication mechanism. Please see the Authentication details page for more information. Default Value: /var/metacat/certs/password	/var/metacat/certs/password
auth.url	The URL of the server that Metacat should use for authentication. Default Value: ldap://ldap.ecoinformatics.org:389/	ldap://ldap.ecoinformatics.org:389/
auth.surl	The URL of the server that Metacat should use for secure authentication. Default Value: ldap://ldap.ecoinformatics.org:389/	ldap://ldap.ecoinformatics.org:389/
auth.base	The base part of the distinguished name that Metacat uses for authentication. Default Value: dc=ecoinformatics,dc=org	dc=ecoinformatics,dc=org
auth.allowedSubmitters	A semicolon delimited list of users who should be allowed to submit documents to Metacat. If no value is specified, all users will be allowed to submit documents. Default Value: (none)	uid=youruser,o=NCEAS,dc=ecoinformatics,dc=org
auth.deniedSubmitters	A semicolon delimited list of users who should NOT be allowed to submit documents. If no value is specified, all users will be allowed to submit documents. Default Value: (none)	uid=youruser,o=NCEAS,dc=ecoinformatics,dc=org
ldap.connectTimeLimit*	The time in milliseconds allowed for LDAP server connections. Default Value: 5000	5000
ldap.searchTimeLimit*	The time in milliseconds allowed for LDAP server searches. Default Value: 30000	3000
ldap.searchCountLimit*	The number of return entries allowed for LDAP server searches. Default Value: 30000	30000
ldap.referral*	The type of LDAP referrals to use. Possible values are “follow”, “throw” or “none”. Refer to LDAP documentation for further information. Default Value: follow	follow
ldap.onlySecureConnection*	Determines whether to use only a secure LDAP server. Acceptable values are “true” and “false”. Default Value: false	false
ldap.onlySecureReferalsConnection*	Determines whether to only use a secure referral server. Acceptable values are “true” and “false”. Default Value: false	false

16.6. XML/EML Properties

Metacat’s XML/EML properties are described below. These properties can only be edited manually in the metacat-site.properties file.

Property	Description	Example
xml.saxparser	The SAX parser used to parse XML documents. Metacat requires a SAX2-compatible XML parser. Default Value: org.apache.xerces.parsers.SAXParser	org.apache.xerces.parsers.SAXParser
xml.eml2_0_0namespace	The namespace of EML 2.0.0 documents. Default Value: eml://ecoinformatics.org/eml-2.0.0	eml://ecoinformatics.org/eml-2.0.0
xml.eml2_0_1namespace	The namespace of EML 2.0.1 documents. Default Value: eml://ecoinformatics.org/eml-2.0.1	eml://ecoinformatics.org/eml-2.0.1
xml.eml2_1_0namespace	The namespace of EML 2.1.0 documents. Default Value: eml://ecoinformatics.org/eml-2.1.0	eml://ecoinformatics.org/eml-2.1.0
xml.packagedoctype	The doctype of a package file. The system will only recognize documents of this type as package files. See: package documentation. Default Value: -//ecoinformatics.org//eml-dataset-2.0.0beta6//EN	-//ecoinformatics.org//eml-dataset-2.0.0beta6//EN -//ecoinformatics.org//eml-dataset-2.0.0beta4//EN
xml.accessdoctype	The doctype of an access control list (ACL) file. The system will only recognize documents of this type as access files. See: access control documentation. Default Value: -//ecoinformatics.org//eml-access-2.0.0beta6//EN	-//ecoinformatics.org//eml-access-2.0.0beta6//EN -//ecoinformatics.org//eml-access-2.0.0beta4//EN

16.7. EZID Properties

The EZID service assigning Digital Object Identifiers (DOIs) is included in the Metacat service.

Property	Description	Example
guid.ezid.enabled	The enabled status of the EZID service	true
guid.ezid.username	A registered user name in the EZID service	apitest
guid.ezid.password	The password for the user name
guid.ezid.baseurl	The base ulr of the specified EZID service	https://ezid.cdlib.org/
guid.ezid.doishoulder.1	The DOI shoulder associated with the EZId account	doi:10.5072/FK2

16.8. Sitemap Properties

Metacat automatically generates sitemaps for all all publicly-readable datasets and stores them in the sitemaps subdirectory under Metacat’s deployment directory.

Property	Description	Example
sitemap.enabled	Whether or not sitemaps are enabled.	true
sitemap.interval	The interval, in milliseconds, between rebuilding the sitemap(s).	86400000 (24hrs)
sitemap.location.base	Base part of the URLs for the location of the sitemap files and the sitemap. index. Either full URL or absolute path. Trailing slash optional.	https://my-metacat.com
sitemap.entry.base	Base part of the URLs for the location entries in the sitemaps. Either full URL or absolute path. Trailing slash optional.	https://my-metacat.com/dataset

16.9. Additional Properties

Additional configuration properties are described below, though there are many more that can be manually edited in the properties file directly. Properties that can only be edited manually in the metacat-site.properties file are marked with an asterisk (*). All others are managed with the properties configuration utility.

Property	Description	Example
plugin.handlers	Implementations of the plugin interface: edu.ucsb.nceas.metacat.plugin.MetacatHandlerPlugin can be listed Default Value: blank	org.example.CustomActionHandler
event.log.deny.ipaddress*	A list of IP addresses whose actions will not be logged when Metacat records Previously property name: event.log.blacklist.ipaddress	192.168.0.1;255.255.255.255
event.log.deny.subject*	A list of subjects (strings) whose actions will not be logged when Metacat records events/logs in the db. Previous property name: event.log.blacklist.subject	bbelcher;http://orcid.org/0000-0012-3456-789X