Advanced Configuration: Difference between revisions

Latest revision as of 19:08, 1 July 2025

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

Configuration Details

The following sections show the available properties and sample values that can be used in the com.carfey.properties properties file. While properties format is shown, all the same configuration items apply to yaml support. See Properties/Yaml File for more details on this file.

Authentication Properties

# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator

#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# As of Obsidian 2.1.1, you can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# As of Obsidian 2.1.1, you can specify the SECURITY_AUTHENTICATION. Defaults to simple. 
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# As of Obsidian 3.5.1, you can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account) 
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# As of Obsidian 3.5.1, this is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# As of Obsidian 3.5.1, this determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# As of Obsidian 3.5.1, if anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with 
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

SMTP Mail Properties

# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port 
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
[email protected]
mail.smtp.password=PASSWORD


# As of Obsidian 2.5.0, we support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session

Database Properties

# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL
	

# As of Obsidian 2.5.0, we support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here. Available as of version 2.1.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public. Available as of Obsidian 2.1.1. 
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# As of 3.4.0, you can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored. 
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

Logging Properties

As of Obsidian 5.0.0

Please see Log4j2 configuration

Before Obsidian 5.0.0

Please see Log4j Configuration

Miscellaneous Properties

# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# As of 2.8.0, if you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# As of 2.9.0, you can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# As of 3.0.0, Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# Obsolete as of 4.0.0. As of 3.4.0, the base URL used to resolve links in the Obsidian web app can be overridden. This is typically only required when a load balancer or proxy is used to access Obsidian.
com.carfey.obsidian.baseHrefUrl=http://myhost:8080/obsidian

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true

Table Prefixes

As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

Properties/Yaml File

The above configuration must reside in a properties file named com.carfey.properties or a yaml file named com.carfey.yaml found according to the rules of ClassLoader.getResource. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include WEB-INF/classes/com.carfey.(properties/yaml), a com.carfey.(properties/yaml) file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in obsidian-props.jar for standalone deployments. Prior to Obsidian 3.6, this file had to exist on the classpath, even if only using the override options below to configure Obsidian.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property carfey.properties.file. All expected properties must be specified in either the default com.carfey.properties file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: -Dcarfey.properties.file=/home/obsidian/obsidian.properties.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property carfey.yaml.file. All expected configuration values must be specified in either the default com.carfey.yaml file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: -Dcarfey.yaml.file=/home/obsidian/obsidian.yaml.

As of Obsidian 2.1, you may also use a programmatic properties override. Simply call com.carfey.jdk.sys.Configurator.setOverride(Properties props) as early as possible in the application startup. To quote the javadoc of this method, For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:

System Property
Environment Variable - overridden by System Property
Properties - overridden by Environment Variable and System Property

Notifications Configuration

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the Dispatch category of the scheduler settings screen. Defaults are provided, but you can update them appropriately for your needs.

Dependent Libraries

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory.

As of Obsidian 2.5.0, our installer supports selective conflict management.

Common

obsidian.jar. Core Obsidian lib.
gson-2.10.1. Supports REST API and web administration.
jmustache-1.15.jar. Provides email templating.
log4j-api-2.17.0.jar, log4j-core-2.17.0.jar. Obsidian logging uses log4j2.
snakeyaml-2.3.jar. Support for YAML configuration.

Databases

h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

Mail

activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

Scripts

apache-groovy-all-4.0.24.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

Web Admin

dom4j-2.1.3.jar. XML utilities.
flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
opencsv-5.4.jar. Support for CSV downloads in UI.

Prior to Obsidian 6.0.0, the following library was in use.

groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

Prior to Obsidian 5.4.0, the following library was in use.

gson-2.8.6.jar. Supports REST API and web administration.

Prior to Obsidian 5.2.0, the following library was in use.

jakarta.activation-1.2.1.jar. Used for email notifications.

Prior to Obsidian 5.0.3, the following older libraries were in use.

Obsidian 5.0.2 log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
Obsidian 5.0.1 log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
Obsidian 5.0.0 log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

Prior to Obsidian 5.0.0, the following older libraries were in use.

activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
dom4j-1.6.1.jar. XML utilities.
gson-2.7.jar. Supports REST API and web administration.
bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
jmustache-1.12.jar. Provides email templating.
h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
log4j-1.2.9.jar. Obsidian logging uses log4j.
mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
opencsv-3.8.jar. Support for CSV downloads in UI.
flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

Prior to Obsidian 4.5.1, the following older libraries were in use.

groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

Prior to Obsidian 4.0.0, the following older libraries were in use.

javax.mail-1.5.2.jar. Used for email notifications.
jstl.jar, standard.jar. Web utilities. Only required in web administration.
gson-2.2.2.jar. Supports REST API and web administration.
groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
jmustache-1.8.jar. Provides email templating.
h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

Prior to Obsidian 2.9.1, the following redundant library was in included in the Obsidian packaging.

smtp.jar. Used for email notifications.

Prior to Obsidian 2.2.0, the following older libraries were in use.

groovy-all-1.7.6.jar
jython.jar (version 2.5.2rc2)

Prior to Obsidian 2.1.1, the following libraries were also included.

carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

Prior to Obsidian 2.1.0, the following older libraries were in use.

ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

Prior to Obsidian 1.5, the following older libraries were in use.

gson-1.5.jar. Supports REST API and web administration.

Required Libraries for Embedded API

To use the Embedded API, the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the standalone directory if your installation. The com.carfey.properties file can be extracted from the obsidian-props.jar in the standalone directory, or from an Obsidian WAR file under WEB-INF/classes.

com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-props.jar, which contains the configuration file
obsidian.jar
dom4j-2.1.3.jar
flexmark-0.62.2.jar, flexmark-util-0.62.2.jar
gson-2.10.1
log4j-api-2.17.0.jar, log4j-core-2.17.0.jar
Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:

jmustache-1.15.jar
- jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
- angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
- activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:

apache-groovy-all-4.0.24.jar
bsh-2.0b5.jar
jruby-9.2.17.0.jar
jython-standalone-2.7.2.jar

Disabling Job Execution & Scheduling in the Web Application

See the instructions within the Getting Started Guide.

Disabling Automatic Database Updates