This version of the manual refers to an earlier version of the software.



Configuration is normally obtained from a file in .properties format. A sample file, called, is included in the distribution archive. It is recommended to make a copy of this file and use the copy as your configuration file. It can be located anywhere, and named anything.

To tell the application where the file is located, supply the -Dcantaloupe.config VM option, pointing to an absolute or relative path to the file. (See Getting Started for examples.)


Configuration files may contain an extends key pointing to the pathname or same-directory filename of another configuration file. This enables multiple instances to share common configuration keys.

Keys in child files override ones in parent files. When the same key is defined in multiple files, instances will use the most specific one.

Multiple extends keys in the same file are not supported. If they are present, only the last one will be used.

Live Changes

The configuration file will be automatically reloaded within a few seconds of a change. Changes to most keys take effect immediately, but some require a restart; see the inline comments for documentation of which.

When using inheritance, any file in the extends chain that changes will be reloaded by all instances in whose extends chain it appears.

Remote Changes

The configuration can be updated remotely via the HTTP API. When a change is received, it will be activated immediately and written out to the configuration file, if it is writable.

When using inheritance, a key will be written to the most specific file that already contains it, or to the main (child) file, if none already contain it.