There is a file called src/condor_utils/param_info.in and in it are definitions like this:
[SCHEDD] default=$(SBIN)/condor_schedd win32_default=$(SBIN)\condor_schedd.exe type=path reconfig=true customization=seldom friendly_name=Schedd usage=Where are the binaries for these daemons? tags=master
Nearly all of the fields are optional, several are not currently used, but may be in the future.
The attributes that you really need to care about are default, win32_default, type, friendly_name, and tags.
Required fields
The parameter name in square brackets marks the beginning of an entry.
- default - The default value. (ex. $(SBIN)/condor_master, 10, false), default may have no value, but the default keyword is required.
Optional fields
- win32_default - default value for Windows, if this is not specified, default is the default value for all platforms
- type - The type. Valid values are: bool, double, int, long, path, string. path is like string, but / will be changed to \ for Windows. long is a 64 bit integer. The default type is string. be sure to use path instead of string for paths
- friendly_name - A more human friendly version of the parameter name, don't bother to fill this in if you're just going to remove '_' from the parameter name.
- customization - How often is it changed by users? const, normal, seldom, expert, devel. default is SELDOM.
- const - things which should never be changed (HOUR, MINUTE).
- normal - customization is likely, (LOCAL_DIR)
- seldom - customization is unlikely, and default value should be shown to non-expert users (MASTER_LOG)
- expert - customization is unlikely, and default value should be hidden from non-expert users.
- devel - customization at developer request only, all evidence of this param is burn-before-reading.
- reconfig - true or false. If true, the value can be changed with condor_reconfig; otherwise it will only be respected on daemon restart. (TODO: check). default is TRUE. This will be changed to restart*=false/true in the future. It is fine to leave this empty for reconfig=true params if you also set *review.
- range - for type=int, long or double this is a pair of comma separated values indicating the minimum and maximum allowed values. You can omit the second number to indicate INT_MAX or DBL_MAX respectively. (ex range=1024,; range=1,1000000000), default is type_MIN, type_MAX. Range has no meaning for non-numeric params, you can remove range=.* when you see it.
- aliases - List of other parameter names which are essentially identical to this use, generally used for backward compatibility. (ex aliases=GROUP_DYNAMIC_MACH_CONSTRAINT)
- version - The version the setting was added. The default is 7.1.0 (when the current parameter system was created), new parameters should get a value, old ones are fine without it.
- usage - Brief information on how to set the parameter. (ex. to specify that each machine has its own file system) Better to leave this empty than have something unhelpful to users here.
- tags - Comma separated (NO SPACES) list of tags to identify the setting. If the setting is only relevant for a particular program or daemon, list that daemon here, minus any condor_ prefix (ex. schedd, submit).
- <platform>_default - default value for <platform>, where <platform> can be a case-sensitive partial match of the NMI platform name. (ex x86_64_default, or Fedora19_default). Use this to give a different default value in NMI for a platform. Since this only works when the cmake PLATFORM setting is set, it can't be relied on to work outside of NMI. Also, can't be used if there is a win32_default.
- review - For 8.1 series ? indicates that the parameter has not yet been reviewed since the great param overhaul of 8.1. After you have verified that the above values are complete and correct for a parameter, replace ? with your username.
Further discussion
The machinery which uses the above information is not yet complete, this is why things like the id field can be left as it is among the other things.
Items with review=? should be reviewed for correctness and completeness. and then the review value set to the username or initials of the reviewer. In particular, check for these things:
::* Is the default correct? If no default, is that reasonable? should there be a different default for windows? ::* Is the type correct? Note that
No extraneous whitespace. Whitespace is preserved in default values. You've been warned.
Be aware that the default is internally implemented as a string, What you see is exactly what you get. This includes trailing spaces. For those parameters that are type int,long,double or bool. the default is also stored as a c++ native type, if the value will parse as that type without any math or substitutions.
You may NOT add variables that:
- requires a runtime, or nonimmediate, default, like
NUM_CPUS. You CAN however, make a default which is an expression based upon another configuration file parameter. And you can reference the detected params, OPSYS, ARCH, etc. - follow a pattern like *_FOOBAR that you cannot specify all cases to. (You'd write A_FOOBAR, B_FOOBAR, C_FOOBAR as individual cases of the above snippet). (future work may allow this). Supporting this is a future work item.
Currently, the param() system does not EXCEPT when an entry is not in the default table. It is our hope and dream that one day all of our entries will be in the default table and EXCEPT will be the default case. Of course, there is an interface into param() which doesn't except no matter what, to implement those features which param() things at runtime picked out of another config file entry.
Things to Note!
- For entries in the default table, the hard coded defaults in the source code are ignored. If the variable is not in the table, the in code defaults are utilized.
Edit Notes
This was once AddConfigParams; if you want older edit history, go there.