[glue-wg] Values with additional sematic meaning.

[Paul Millar]

Hi all,

One of the complaints I've heard from people is that GLUE schema doesn't have 
a mechanism for knowing that certain results are invalid.  In my "spare 
time", I put together some material that might be of use here.

Of course, this is just a first draft; comments gratefully appreciated.

Cheers,

Paul.

PS.
my thanks to Graeme Steward for his comments and suggestions.

-------------

GLUE proposal on values with additional semantic meaning.
----


Introduction
---

GLUE Schema provides a common method of providing information about a
Grid such that specific knowledge of that Grid is not needed to
appreciate its current state.

The current GLUE schema assumes that all information is available and
that any static information has been correctly configured.  This is not
always true: for whatever reason, information may be temporary or more 
permanently unavailable or some static information may be left unconfigured.

These imply that some additional (semantic) meaning of values is
needed.  This is most naturally accommodated by returning a special (or
"illegal") value: a value that should not occur during normal
operation.

This is already in practise; however it is not specified within GLUE, so 
different implementations can choose different values.  Knowledge of whether 
a particular value is valid then becomes information-provider specific, going 
against the spirit of the GLUE Schema.

This document aims to rationalises and standardises values that have some
additional semantic meaning.  It is split into two further sections: use-cases
and proposed values.


Use-cases:
---

Two scenarios are considered:

Scenario 1. a static value has no (good) default value and has not
been configured.

Some static values have no good default value.  This may be because
the configuration requires some knowledge of a site's configuration or
for some other reason.  Whilst this value should be altered to reflect
the site's configuration this might not happen[1], so exposing the
application's default configuration.  Given there is no (good) default
value, what should this value be?

[1] We note the available of tools such as YAIM to assist in
configuration of EGEE sites, which will reduce the likelihood of this
scenario.  However, 1. not all sites are configured with YAIM, 2. not
all Grids have a tool like YAIM, 3. Upgrading components may result in
changes in configuration, so increasing the likelihood of this
problem.



Scenario 2. information provider is unable to obtain a dynamic value.

A dynamic value is provided by an information provider by querying the
Grid resource.  This query will use a number of ancillary resources
(e.g., DNS, network hardware) that might fail; the service itself
might fail.  Given a lack of information[2], what value should the
information provider return?

[2] If caching of previous results is available, temporary failures
may be mitigated.  However, it is an open question for how long any
such cached information should be permitted.


Proposed illegal values:
---

This section describes a number of values that can be represented
within a given address space (e.g., UTF-8, Integers, FQDNs, IPv4
address space).

With Scenario 1, configuration SHOULD use these default values
wherever possible; likewise, dynamic information provides SHOULD use
these default values whenever they wish to indicate a problem
gathering information.

The semantic meaning SHOULD BE limited to simply that the value is
invalid and is not to be relied upon.  A client using this information
SHOULD NOT draw any conclusions as to why the information is invalid
from the information presented here.


1. All GLUE-specific enumerated types:
	SHOULD use the designated "unknown" value.

  Rational:

  If a value is unknown, it should be specified as such.  Either this
  or the GLUE schema clearly state that, should some values be unknown
  that the whole entry should not be reported.


2. Simple strings (UTF-8): SHOULD use "ILLEGALVALUE".

  Rational:
 
  Upper-case letters make it easier to spot and a single word avoids
  white-space issues.

  This is a default option for strings that have no widely-known
  structure.  If a value is from a more restrictive sub-type
  (e.g. FQDNs), then the rules for more restrictive form SHOULD be
  used.


3. Fully qualified domain names: SHOULD use a hostname ending
	"invalid." for scenario 2. and either "example.org."
	or "example.com." for scenario 1.

  Rational:

  RFC 2606 reserves the ".invalid" TLD as always invalid and clearly
  so.  For dynamic information a value of "unknown.invalid." MAY be
  used.  If an alternative is used, it SHOULD use the TLD ".invalid".

  RFC 2606 also defines the ".example" TLD and two second-level
  domains: "example.org" and "example.com".  These domains have the
  advantage of ending with a recognisable TLD, so looking like a DNS
  name.  Default configuration SHOULD use DNS names that end
  ".example.com." or ".example.org."

  The final dot at the end of the DNS name SHOULD be included as it
  prevents local DNS expansion.


4. IPv4 addr: SHOULD use 192.0.2.250

  Rational:

  There are several portions of IPv4 addresses that should not appear
  on a network, but none that are documented as being illegal.  Using
  an arbitrary address leads to the risk of side-effects.

  The best option is an IP address from the 192.0.2.0/24 subnet.  This
  subnet is defined in RFC 3330 as "TEST-NET" for use in documentation
  and example code.  Although any IPv4 address from 192.0.2.0/24 MAY
  be used, the above address SHOULD use for consistency.


5. IPv6 addr: SHOULD use 2001:DB8::FFFF

  Rational:

  There is no documented illegal IPv6 address.  RFC 3849 reserves the
  address prefix 2001:DB8::/32 for documentation.  For consistency,
  the address SHOULD BE the one noted above.


6. Counting/Natural numbers:
	SHOULD use 0

  Rational:

  Counting- (also known as Natural-) numbers exclude the number zero,
  so information provider SHOULD use this value to indicate an illegal
  value.


7. Integers:
	SHOULD use MAXINT (maximum value representable in the domain).
		For int32 this is 2,147,483,647
		 "  uint32 this is 4,294,967,295
		 "  int64 this is 9,223,372,036,854,775,807
		 "  uint64 this is 18,446,744,073,709,551,615

  Rational:

  For non-negative integers, all numbers expressible within the
  encoding (int32/uint32/etc...) are valid so there is no safe choice.
  Although any value may be chosen, the value least likely to be
  encountered in any given domain is that domain's maximum value.

  If an unsigned integer is encoded as a signed integer, it is
  possible to use negative numbers safely.  However, these numbers
  will be unrepresentable if the number is stored as an unsigned
  integer.

  For values that might be a positive, zero or a negative integer, all
  numbers expressible within the encoding (unsigned int) are valid so
  there is no safe choice.  For consistency, the MAXINT value SHOULD
  be used.

  Information providers SHOULD NOT attempt to conveying further
  semantic distinction by using more than one illegal number.


8. Filenames:
	SHOULD use "ILLEGALPATH".

  Rational:

  As with the simple string, a single upper-case word is recommended.


9. Uniform Resource Identifier (URI): schema-specific

  Rational:

  RFC 3986 defines URIs as a "federated and extensible naming system."
  All URIs start with a schema-name part and no schema-name has been
  reserved for illegal or example values.  For any given URI schema,
  it may be possible to define an illegal value within that
  name-space.  If a value has only one valid schema, the illegal value
  should be taken from that schema.  If several schemata are possible,
  one should be chosen.

  For schemata that include a reference to an Internet host
  (e.g. http, httpg, mailto), an illegal value SHOULD be derived by
  using an illegal FQDN (see above).

  For other schemata, some element should indicate that the value is
  illegal.  This is subject to further work.


10. X509 Distinguished Names:
	SHOULD include a RDN of CN=ILLEGALUSER

  Rational:

  X509 uses a X500 namespace, represented as several RDNs concatinated
  by commas.  The final RDN is usually a single common name (CN).

  It is possible for more than one CN to be present, allowing
  inclusion of additional sematic meaning.  This is outwith the scope
  of the document.



Definition of words:
---

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are meant as described in RFC 2119.  A brief summary is given
here.


1. MUST (or "REQUIRED" or "SHALL") means that no deviation is allowed
   from conforming software.

2. MUST NOT (or "SHALL NOT") means complete prohibition of this
   behaviour with conforming software.

3. SHOULD (or "RECOMMENDED") means that there may be reasons why
   conforming software does not to adopt this behaviour, but all the
   effects of an alternative behaviour must be understood and
   considered before choosing a different course.

4. SHOULD NOT (or "NOT RECOMMENDED") means that there may be reasons
   why conforming software adopts this behaviour, but all the
   effects of an alternative behaviour must be understood and
   considered before choosing a different course.

5. MAY (or "OPTIONAL") means an item is completely optional.