MASTERKEY ADMIN SITE CONFIGURATION
----------------------------------

APACHE2 CONFIGURATION
---------------------

Top-level configuration of older MKAdmins (in the Apache2
configuration fragment) used to be by specifying two directories where
MKAdmin's own configuration files are held: an application directory
specified by the MAconfigdir environment variable and a system
directory (provided as part of the MKAdmin package) specified by the
MAsysdir environment variable.

Since release 1.21 of 30 April 2010, MKAdmin is now preferentially
configured by a _path_, which is specified in the MAconfigpath
environment variable.  It's colon-separated, like this:
	PerlSetEnv MAconfigpath /path/to/application/mkadmin:/etc/masterkey/admin/system

This is more general and flexible as it allows any number of
directories to be used rather than only one or two.  The old approach
is still supported for backwards compatibility, but is deprecated.
Old configurations like this:
	PerlSetEnv MAconfigdir xxx
	PerlSetEnv MAsysdir yyy
it can and should be changed to:
	PerlSetEnv MAconfigpath xxx:yyy


LAYOUT OF EACH CONFIGURATION DIRECTORY
--------------------------------------

Each directory within /etc/masterkey/admin/conf.d/ represents a
separate Admin-UI site.

Within each directory, SITE.config configures the site as a whole, and
each other *.config file represents an Admin-UI tab.  In general each
such tab of a site will address a different Torus, but that is not
a requirement: for example, two different CSS skins might be used to
provide different views of the same Torus.


CONFIGURATION FILE FORMAT
-------------------------

The format is the same for whole-site configuration and tab
configuration files, although the particular keys that are recognised
are different in these two cases.

- Comments, running from a hash (#) to the end of the line, are
  discarded.

- Blank lines are ignored.

- Any line of the form "%define NAME=VALUE" sets the value of the
  named symbol; these values may be re-used in subsequent lines by
  sequences of the form "${NAME}".  The braces surrounding the NAME
  are mandatory.  (For backwards compatibility, the form "$(NAME)" is
  also supported, but this is deprecated.)

- Expansion of ${NAME} sequences may be inhibited by preceding them
  with another $ sign as in $${NAME} (like the use of %% to produce a
  literal % character in a printf() format string).  In this case, the
  leading dollar sign is simply discarded.  This allows a literal
  ${foo} to be passed through for subsequent expansion, e.g. by the
  code that interprets the realmOnNew.*.url configuration directive.

- Any line beginning with "%include" specifies the name of another
  configuration file, from the same directory, whose contents are read
  as though included inline.  If the named file does not exist, then
  it is sought in the next directory along the configuration path, and
  so on.

  Included filenames may include paths, which are interpreted relative
  to the directory of the initial file.  Included files may include
  further files, to any depth.

  If the name of the file to be included is enclosed in angle
  brackets, like this:
	%include <foo.config>
  Then search starts at the next directory along the path rather than
  in the current directory.  This mechanism allows a file called
  "foo.config" to use such a line, resulting in falling back to the
  next directory, without an infinite recursive include.

  Finally, if the string following the %include directive begins with
  "http://" then it is recognised as an HTTP URL. The content is
  fetched from the specified URL, and interpreted as a Torus record
  (or a list of one Torus record, in the case of URLs that include
  searches). The key=value pairs in the record's "final" layer are
  interpreted as key:value configuration directives. Keys in this
  layer have underscores in their names substituted for periods, so
  that for example "field_zurl_name" becomes "field.zurl.name". This
  is because literal periods cannot appear in XML tags.

- All other lines are simple key-value pairs of the form <name>:
  <value>, like RFC-822 mail headers.

  Any value (as opposed to a whole line) that begins "%include" is
  replaced by the contents of the file whose name follows that token.
  This is useful for long values such as help-texts.

Apart from configuration files proper, application configuration can
contains files of HTML or CSS content, to be included as %include
values, and Torus profiles.  These are not discussed here.


WHOLE-SITE CONFIGURATION
------------------------

redirectToTab -- if defined, the name of a tab which the home page
	redirects to -- so that that there is no top-level
	introduction page, only a default tab.

frontPageTitle -- if redirectToTab is not defined, then a simple login
	page is presented at the home page.  The title of that page is
	specified here.

frontPageH1 -- Top-level heading on front page, if any.  Defaults to
	the same as frontPageTitle if not specified.  May contain
	HTML.

logo -- If specified, the URL of a logo to show beneath the page title
	on the front page, if any.

css.everywhere -- CSS code which is used to skin all pages of the
	site, including the front-page, if any.

css.frontpage -- CSS code which is used to skin the front-page, if any.

login.<NUMBER>.authRealm
login.<NUMBER>.authRedirect -- Together, pairs of these elements
	define the set of user registers where the Admin UI front page
	should attempt authentication, and what to do when one
	succeeds.  Once a username/password pair has been provided, it
	is searched for in login.1.authRealm using the specifed realm,
	then login.2.authRealm if that fails, and so on.  As soon as a
	match is found, the user's browser is redirected to the URL
	specified in the corresponding login.<NUMBER>.authRedirect.
	In that way, a single unified login page can send the user to
	either a global-administrator area or a local-administrator
	area, depending on which user register is matched.


TAB CONFIGURATION
-----------------

tab.<NUMBER>.caption
tab.<NUMBER>.tab -- Together, pairs of these elements define the
	set of tabs that are displayed along the top of each page of
	the admin site (with the exception of the top-level login
	page, if any).  For each <NUMBER>, "caption" contains the text
	to be rendered in the tab, and "tab" contains the name of
	the tab (in the sense of tab contents) which is used when that
	tab (in the sense of the sticking-up bit) is clicked.
		tab.<NUMBER>.subsite -- deprecated synonym

siteTitle -- the whole-site title used as a short prefix for every
	page in every tab.

title -- the title of this tab of the admin system, displayed
	prominently on the screen.

email.event.<EVENT> -- if set, then send an administrative email alert
	when the specified event occurs -- e.g. "newRecord" for adding
	a new record. For backwards compatibility, the old
	"sendEmail.add" is recognised as well as
	"email.event.newRecord".

email.toAdmin -- address to which administrative alert emails such as
	new-record notifications should be sent. For backwards
	compatibility, the old "adminEmail" property is also
	recognised.

email.from -- Address from which administrative emails (password
	reminders, new-record notifications, etc.) appear to be sent.

email.host -- Host used to send email. Messages are fed to the SMTP
	server on port 25 of the specified host. Defaults to
	"localhost".

email.hello -- Host specified in the SMTP "HELO" command. Most SMTP
	servers don't use this, but it should in theory identify the
	host that is requesting email to be sent. A good choice is the
	hostname by which the MKAdmin site is accessed.

iframeURL -- if defined, the URL of a page to display as an iframe
	below the site header, so that the nominated page appears to
	be one of the tabs.  (Actually, an iframe is not a very good
	way to implement this, because it wants to be fixed-size, but
	it's better than nothing.)

homeHtml -- HTML code to be displayed in the tab's home page,
	/<TAB>/home.html.  Often provided using %include.

profilePath -- the path, relative the directory in which the
	configuration file is found, where Torus profiles are
	located.

type -- the type of object to be handled by this Admin UI.  This is
	used to identify a profile in the directory specified by the
	profilePath, which specifies what fields the objects should
	contain, and for various other purposes.

realm -- the URL of the realm containing the objects to be maintained.
	These objects MUST be of the same type as specified above,
	otherwise Bad Things might happen (e.g. violations of
	causality, rips in the fabric of space-time, segmentation
	violations).

torusRealm -- If defined, then this is the realm in which all
	operations in the Torus take place -- GETting, PUTting,
	POSTing, DELETEing; otherwise, the realm specified by the
	logged-in user's identityId is used.  By setting this, it is
	possible to restrict a tab such that all operations on it
	are within a single shared realm.

constrainIdentity -- If defined, then all objects visible in the
	tab are constrainted to have the same identityId as the
	logged-in administrator.  This acts as a limitation on what
	records are visible to be listed, searched and scanned, and
	forces all newly created records to have the appropriate
	identityId.

authRealm -- the URL of the realm containing the identities as which
	the user can log in.  For the "Admin Users" admin site, this
	is the same as the main torus (i.e. it authenticates against
	the records that it owns) but no other admin site should do
	that.  If this element is not provided, then authentication is
	not possible, and the Admin Site is read-only, as in the
	"dummy" site for IRSpy (UNUSED/irspy.config).

authDomain -- an opaque string specifying the domain of tabs with
	which authentication of sessions is shared.  After logging on
	with this tab, the same logged-in identity is used for all
	other tabs that have the same authDomain.

css.everywhere -- CSS code which is used to skin all pages of the
	site, including sites within tabs.  This will often take the
	form "%include <somefile.css>".

css.site -- CSS code which is used to skin all tabs of the Admin UI.
	This will often take the form "%include <somefile.css>".

css.tab -- CSS code which is used to skin the specific tab of the
	Admin UI.  This will often take the form "%include
	<somefile.css>".  (In fact, the css.site and css.tab
	properties are implemented exactly the same way, but it's
	useful that there are two of them, and the names provide a
	helpful hint for how they can be used.  In general, the
	styling in css.site does the heavy lifting, and css.tab just
	tweaks colours.
		css.subsite -- deprecated synonym.

noworld -- May be set true to indicate that the tab handles a
	Torus that does not have any "world" records (either of its
	own or inherited from parent), in which case the "All Xs" part
	of the menu panel and the "Base value" column of the editing
	table will be omitted.

listLoginFor -- If specified, this is the name of a tab for which
	"act as" links should be provided in the page listing local
	records (including as search results) and on the pages for
	individual records.  This is useful in the admin tab, allowing
	a single click to authenticate the senior administrator as any
	of the regular administrators.

authUserCookie -- If set, the name of an additional cookie that is
	used to simplify sharing of logins with related sites.  On
	login, the named cookie is set to the ID of the logged-in
	user.  Similarly, if the cookie is found to be set in a
	session that is not logged in, the identity of the specified
	user is assumed ... which is NOT SECURE but apparently we want
	to do it anyway.

showURI -- if set, then the URI to the Torus WSAPI that underlies each
	displayed list or record is emitted, and made a link into that
	WSAPI.  This is only useful for debugging.

pageSize --  if set, the search page will not print more hits of
	pageSize and enable paging.  The default value is 50.  Valid
	values are 1..200

showFacets -- if set, then facets will be displayed in the sidebar.

facetList -- a pipe-separated list of names of facets to include in
	output when showFacets is true. At present each pipe-separated
	element is simply a facet name such as "serviceProvider", but
	future extensions may allow other aspects of the facet
	behaviour to be specified using more complex syntax.

facet.<NAME>.caption -- caption to use as the heading for the named
	facet, in place of the facet-name itself.

facet.<NAME>.separator -- If the named field is made of multiple facet
	values (as for example in the comma-separated categories in
	the "categories" field, this configuration elements indicates
	what sequence the field should be broken on. Special values
	such as commas and spaced must be specified as octal escapes,
	"\054" and "\040" to prevent interpretation within the Torus
	protocol.

facet.<NAME>.op -- operator to use, in place of the default "==", when
	formulating queries based on facet values.

maxFacets.<NAME> -- limit the maximum number of terms emitted under
	the <NAME> facet, e.g. maxFacets.opacVendor: 5

showTagCloud -- if set, then a tag cloud will be displayed at the
	bottom of the sidebar.

showProvider -- tables of results include a column for the
	serviceProvider field, which is appropriate for searchables
	but not for identities.

fieldList -- a comma-separated list of fields to be included in
	checklist pages, in addition to displayName. Overrides
	showProvider if both are included.  See also
	caption.heading.<FIELD>.

tagCloudLevels -- if not provided, levels defaults to 8

disableUserLink -- if set, then the logged-in user's name, displayed
	in the usermenu bar, is not a link to the user page.

disableMenu -- if set, then the menu panel on the left side of the
	page is not displayed, and the client area fills the width of
	the browser window.

disableSearch -- if set, then there is no search box or A-Z list in
	the various list pages. This is appropriate for tabs that will
	list very few items, e.g. categories.

disableSearchDays -- if set, then the "changed in last NUM days" part
	of the search form is omitted from list pages.

disableAZ -- if set, then the A-Z list is omitted from the search
	form.

disableActionBar -- if set, then full-record pages (including edit,
	test, etc.) do not include the action bar with the "Full
	View", "Show record" etc. buttons.

disableEdit -- if set, then there are no edit links on list pages
	(checklist and selected records). Cf. linkToEdit.

linkToEdit -- if true, then list pages make the record titles link to
	the edit page rather than the display page, and there is no
	separate column of edit links. Cf. disableEdit.

noMenuItems -- if set, then the menu panel remains (unless disabled
	with disableMenu) but contains no menu items.  This is
	appropriate for tabs that do not exist to maintain sets of
	records, such as the "account", "laccount" and "reports" tabs.

menuHTML -- if set (and if disableMenu or noMenuItems does not render
	it moot), then this is a fragment of HTML that is displayed in
	place of the usual menu items.  When this is in effect, the
	disableHomeLink, nowords, menu.* and usermenu.* items are all
	ignored.

disableHomeLink -- if set, then the "Home" link is omitted from the
	menu panel and the tab name is not a link to the home page.

disableRealmDisplay -- if set, then the realm that the logged-in user
	administrated is not shown in the user-menu bar.

disablePageTitle -- if set, then the page title ("Welcome", "Find
	Searchables", etc.) is omitted from the HTML title and
	top-level heading.

disableRecordLayer -- if set, then the single-record display page does
	not indicate the layer of the record being displayed
	("overlay", "final", etc.)

disableRecordType -- if set, then the single-record display and edit
	pages do not indicate the type of the record being displayed
	or edited ("searchable", "identity", etc.)

disableUserLink -- if set, then the links to the logged-in user's
	details page and password-change page are omitted from the
	user-menu bar.

disableFullRecord -- if set, then the "Full Record" button is not
	displayed on record-display and edit pages, and non-"visible"
	fields can't be seen or edited.

disableManageParents -- if set, then the "Manage Parents" and "Manage
	Masters" links which are usually displayed on pages whose
	realms have a world are instead omitted.

defaultFullRecord -- if set, then the "Full Record" button is not
	displayed on record-display and edit pages, all fields are
	visible/editable.

menu.<SECTION>.<LABEL> -- A set of elements used to provide additional
	entries in the main menu panel.  Each such element indicates
	an entry labelled <LABEL> in the section called <SECTION>,
	linking to the URL specified as the value.  Sections leap into
	existence when required.  Sections are listed in the menu
	panel in alphabetical order, and items with each section are
	also sorted alphabetically.

usermenu.<SECTION>.<LABEL> -- As for menu.<SECTION>.<LABEL>, but the
	menu options only appear when logged in, in the user-menu
	section of the menu panel.

frontPageComponent -- if defined, the name of the Mason component to
	use for the front page of the tab; if not defined, then
	"home.mc" is used.

frontPageKey.<NUMBER> and frontPageValue.<NUMBER> -- key-value pairs
	to pass to the nominated frontPageComponent.  Any number of
	such pairs may be specified

helpPage -- if specified, the URL of a page to be linked, from the
	word "Help", in the far right of the user menu.

listPage -- the URL of the list-of-objects page that is linked to by,
	for example, the [List records] link on the edit page.

submitPosition -- the position of the Submit Changes button on
	checkbox.html.  May be set to "bottom" (the default), "top",
	"both" or (why not?) "neither".

form.onsubmit -- an optional fragment of JavaScript to be run as the
	onsubmit action of the checklist form.  By setting this to,
	for example "return okToChange()", it's possible to have a
	function check whether you really want to proceed or not.

z3950TestingTerm -- the term to be submitted in test searches as part
	of Z39.50 target testing; defaults to "water" if not
	specified.

z3950DateTestingTerm -- the term to be submitted in date searches as
	part of Z39.50 target testing; defaults to "1998" if not
	specified.

usiBaseUrl -- if defined, the base URL of a USI (Universal Searching
	Interface) to be used for USI testing, i.e. invocations of
	ztest.html with the usi=1 parameter.  Should be of the form
	http://ebsco1.indexdata.com:9000. Also used in ninja-test
	links.

usiLoginFromTab -- If defined, then this is the name of a tab (usually
	"identity") by which end-user accounts are maintained. In this
	case, target testing does not specify the realm of the target
	record using ",realm=NAME" in a rich database name, as usual,
	but instead passes in the username and password of an end-user
	associated with the current administrator's realm. This
	sounds complicated, but the bottom line is this: if your
	application is like MKC rather than USI, put
	"usiLoginFromTab:identity" in your configuration.

ninjaTestUrl -- If defined, specifies the base URL of a ninja-test
	system that can be used for exhaustive testing of USI-style
	targets. If not defined, no ninja-test link is emitted.

ninjaTestTorusUrl -- If defined, then ninja-test links include this as
	the torus to consult. Otherwise, those links fall back to
	using the torus in use by MKAdmin itself. This is of value
	when the torus is not accessible to both the MKAdmin system
	and the ninja-test system by the same name -- for example,
	because it is efficient for MKAdmin to use a torus on
	"localhost" but the ninja test has to refer to it by its
	FQDN.

field.<FIELD>.name -- Specifies a human-readable version of the field
	name to use on screen when the default rendering is
	unsuitable.

field.<FIELD>.visible -- If set to 1 (or any true value) then the
	field is displayed by default; otherwise it is displayed only
	if the "Show all fields" button is pressed.

field.<FIELD>.help -- A chunk of HTML used as the help text to
	describe the meaning of this field to users.

field.<FIELD>.clone -- If set true, then when creating a brand new
	record, the initial value for this field is pre-populated from
	its value in the identity object that the author is logged in
	as.  (Be careful when using this with non-identity objects).

field.<FIELD>.editType -- Fields are usually edited using a simple
	textbox, but setting editType can change this.  Currently
	recognised values are:

		text -- a simple textbox.  This is the default, and is
			useful for restoring default behaviour if it
			has been changed by a higher-level
			configuration file.

		scan -- a list is presented of all the values
			currently in use for this field, in this and
			other records.

		options [name1=]val1|[name2=]val2|[name3=]val3 ... --
			a list is presented of the specified hardwired
			options.  If a value is of the form
			<name>=<val> then <name> is displayed but the
			corresponding <val> is stored; if no <name> is
			given then the specified <val> is also
			displayed.

		multiOptions [name1=]val1|[name2=]val2 ... -- as
			"options", but multiple values can be selected.

		select [nameField=]valField catTab -- a list is
			presented of all the values represented in the
			torus in the specified tab.  If <nameField> is
			provided than the field of that name is used
			in the list display and the values of the
			field named <valField> is stored; if no
			<nameField> is given then contents of the
			specified <valField> is also used for display.

		multiSelect [nameField=]valField catTab -- as
			"select", but multiple values can be selected.

	Other values are rejected

field.<FIELD>.height -- if specified, indicates the height of the
	textarea control that should be used to edit this field;
	otherwise a single-line text control is used. Also implemented
	for multiSelect controls.

field.<FIELD>.autoFill -- if defined, specifies the name of another
	field to be autofilled with the contents of this one.  When
	editing, if this field changes and the target field is empty,
	then the newly set value is copied across.  Capital letters
	are downcased, and non-alphanumerics are translated to
	underscores.

field.<FIELD>.unique -- if true, then new records will be rejected if
	the value that they contain for <FIELD> is already found in
	another record in the same realm.

field.<FIELD>.startSection -- if true, then the named field is the
	first in the section whose names is given. This is used by the
	edit page to break up a long list of fields under subheadings.

field.<FIELD>.breakAfterChar -- if defined, then every occurence of
	  the specified value within the field is rendered with a
	  zero-width space immediately after it, allowing the HTML
	  rendering engine to break the string at that point. This is
	  useful in situations such as allowing long compound category
	  IDs to be broken on the vertical bar character.

<CONTEXT>.field.<FIELD>.name
<CONTEXT>.field.<FIELD>.height -- properties to be used in the display
	of fields in a specific named context.  At present the only
	such context supported is "user", indicating the page where a
	logged-in user maintains his own details, password, etc.

user.fields -- if specified, a space-separated list of the fields that
	are displayed on the user page.  If ommitted, defaults to
	"displayName projectManager emailAddress phoneNumber proxyUrl
	comment".

button.<NAME>.position -- the position ("left", "right" or "hidden")
	of the named button on the edit page.  Button names are "save"
	and "cancel".

note.<TAG> -- if specified, a chunk of HTML to be emitted as a note at
	the end of pages with the specified tag, e.g. "all" for
	/SITE/all.html.  It is the responsibility of the pages
	themselves to specify their tag in the invocation of
	shownote.mc

caption.<TOKEN> -- provides a piece of text to be used in place of the
	default text in the context indicated by <TOKEN>.  For
	example, "caption.localValue" provides the text to be used in
	the heading of the table column that contains local data value
	when editing a record.

	Supported caption tokens are:
		actAs
		addFields
		addObject
		addObject2
		allObjects
		allObjectsHeading
		baseValue
		createLink
		createRecord
		deleteObject
		details
		editObject
		find
		hideFields
		list
		listObjects
		localValue
		myObjects
		nameObject
		new
		providerObject
		recordName
		recordNamePlural
		selected
		showFields
		zoomChildren
		reallyDelete -- The sequnce "%s" is replaced by name
		reallyDeleteLast

caption.heading.<FIELD> -- provides a piece of text to be used in
	place of the fieldname as a heading for the table in checklist
	pages. (The old caption.providerObject is retained as a
	backwards compatible synonym of
	caption.heading.serviceProvider).

caption.button.<TOKEN> -- provide a piece of text to be used as the
	name of a button. Supported button-caption tokens are
	"showFields" and "hideFields".

editAfterAdd -- if set, then adding a record to the selected set (from
	the list of available records) results in a redirect to edit
	that newly added record, rather than the default of listing
	all selected records.

copyLibrary -- if set, which is ONLY VALID IN THE "admin" TAB, then
	the "single.html" page includes a button allowing the whole
	library to be copied: all targets and categories.  This is a
	bit monolithic, but the idea of trying to make it fully
	configurable makes me want to weep.  The bottom line is that
	the code invoked by this directive knows how we set up
	Masterkey application, the connections between various realms,
	etc.

cfrepoUrl -- may be set to the base-URL of a connector repo, such as
	"http://cfrepo.indexdata.com/repo.pl/ebscousi".  If set, it is
	taken as the base-URL of CF Repo: displays of connector-based
	records include a link to the connector itself within that
	repo.

addToAll -- if set, which is ONLY VALID IN THE "global" and "cat"
	TABS, then the value is the name of a tab (usually
	"searchable" or "lcat").  Individual record pages will then
	include a link to add the target or category record to the
	Torus realms associated with the nominated tab for all
	libraries in the consortium.

removeFromAll -- if set, which is ONLY VALID IN THE "global" and "cat"
	TABS, then the value is the name of a tab (usually
	"searchable" or "lcat").  Individual record pages will then
	include a link to remove the target or category record from
	the Torus realms associated with the nominated tab for all
	libraries in the consortium.

icondir.<CONTEXT> -- if set, specifies the directory from which icons
	(add.png, edit.png, etc.) are loaded in the specified
	context.

	Three contexts are used: "list" for icons appearing as part of
	a list entry, such as the Edit icons next to targets in a
	list; "toolbal" for icons appearing in a toolbar at the top or
	bottom of a page; and "doc" for icons appearing in
	documentation.

	The value may be relative: "images" is the default and
	"images/24x24" is an option for larger icons than the default
	16x16 set. Alternatively, it may be absolute: for example,
	/static/icons will allow the application-specific
	configuration to incude cusomised icons.

mkWidgets -- if set, then the list of selected items (my.html) offers
	a link to a page that constructs an MKWS widget for
	automatically searching the selected targets.

Other configuration elements may follow.


CREATING REALMS WHEN ADDING A RECORD
------------------------------------

a set of five configuration directives, realmOnNew.*, work together to
establish new realms associated with newly added records.  The
use-case for these is that, when using Torus2, creating a new library
entails making realms to hold its targets and categories.  Each newly
created realm has a URL and a type, and a set of zero or more parents;
each parent has a human-readable name, a priority and a URL.  The
individual directives are as follows:

realmOnNew.<REALMNUM>.url -- specifies the URL of a new realm to be
	created.  This directive is checked for <REALMNUM> = 1, 2,
	etc., and realm creation is deemed complete when the n'th
	directive is not present.

realmOnNew.<REALMNUM>.type -- specifies the type of the new realm --
	"searchable", "identity", etc.  This must be provided for each
	<REALMNUM> that has a URL specified.

realmOnNew.<REALMNUM>.parent.<PARENTNUM>.name -- specifies the
	human-readable name of a parent to be installed for the
	specified new realm.  This directive is checked for
	<PARENTNUM> = 1, 2, etc., and parent creation for realm
	<REALMNUM> is deemed complete when the n'th directive is not
	present.

realmOnNew.<REALMNUM>.parent.<PARENTNUM>.priority -- specifies the
	priority of the new realm's new parent.  The priority must be
	a small integer, with lower numbers indicating higher
	priority.  Conventionally, we use only two values: 1 for
	high-priority parents such as a consoritum-curated selection
	of tagets, and 2 for low-priority parents such as the
	collection of targets reported by the IRSpy toroid.  This must
	be provided for each <PARENTNUM> that has a name specified.

realmOnNew.<REALMNUM>.parent.<PARENTNUM>.refreshAfter -- if present,
	specifies the fresh interval of the new realm's new parent, in
	seconds.  If absent, the default if 0, meaning never do a
	time-based refresh.

realmOnNew.<REALMNUM>.parent.<PARENTNUM>.url -- specifies the url of
	the new realm's new parent.  This must be a corectly formed
	URL which, when dereferenced yields XML in the correct toroid
	format.  It may be an http: URL (the most common case) or
	file: for a local cache, etc.  This must be provided for each
	<PARENTNUM> that has a name specified.


HOW TO SET UP A TORUS
---------------------

The Torus software is designed so that new Toruses spring into being
the first time their world list is accessed, e.g.
	http://coffee.indexdata.dk/torus/admin/records/world/
However, by default a new Torus expects to serve "searchable" records
rather than identities, so it's necessary to tweak the new Torus's
configuration if it's not for searchables.

home$ ssh bagel
bagel$ ssh coffee.indexdata.dk
coffee$ sudo bash
Password: ********
coffee# cd /home/jakub/glassfish/domains/domain1/config/torus/NAME
coffee# vi config.xml

Change the lines

	<recordtype>searchable</recordtype>
	<xsilayertype>searchableTypeLayer</xsilayertype>

to specify whatever type you want to use: for example

	<recordtype>identity</recordtype>
	<xsilayertype>identityTypeLayer</xsilayertype>

This file also contains elements that can be used to specify one or
more parent Toruses from which to inherit records.  (The initial file
generated for a new Torus has this section commented out, but it's
easy to see how to uncomment it and add a parent.)

The Torus logs are at:
	/var/log/masterkey/torus/default.log

and the tomcat6 log at:
	/var/log/tomcat6/catalina.out



HOW TO SET UP A WHOLE NEW APPLICATION
-------------------------------------

Apart from setting up the Toruses for the new application, you'll also
need to manually create the identity record for the Global
Administrator: once you've done that, you can log in using this
account and use it to make all the other admins and targets.

You will need to place the record in a location like:
	/var/lib/masterkey/torus/<torus>/admin/records/wizard/master-user.xml
The name of the file within that directory does not matter.  The
record needs to look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<record URI="record" type="identity">
  <layer name="override">
    <userName>admin</userName>
    <password>admin</password>
    <admin>2</admin>
    <displayName>MKAdmin Global Administrator</displayName>
    <emailAddress>mike@indexdata.com</emailAddress>
    <identityId>admin</identityId>
    <comment>This is the single top-level administrator</comment>
    <id>local-0</id>
    <identity>wizard</identity>
  </layer>
</record>

