Overview and High Level Goals
OpenVault needs the ability to upgrade parts of itself without
requiring that all parts be upgraded at the same time.
Since each of the interfaces used by OpenVault is in fact a language,
we have defined those languages to have names and explicit version numbers
for each version of each language.
This document describes how clients in the OpenVault system negotiate
with the MLM Core to determine which of the OpenVault languages
they would like to use, and which version of that language.
An overview of that negotiation is that when a client connects to the
MLM Core, it announces which language it intends to use,
and which versions of that language it understands.
The MLM Core then picks one of those versions and tells the client
that they will be using that version during the current session.
Decisions, Assumptions, and Limitations
Once the language version negotiation is completed,
the parties are free to use whatever format or structure of
communication will fit into the TCP socket.
In effect, after the semicolon that terminates the "welcome" response,
the socket could even carry pure binary if that were the definition
of the language version that both sides agreed to use.
Interfaces
There are only two messages in the client to MLM connection,
one in each direction:
a hello message goes from the client to the MLM Core, while
a welcome or unwelcome message returns from the MLM Core.
Both messages are sent as simple ASCII text in a normal TCP socket
(albeit with a bit more complexity if message integrity coding
is enabled, see
Interprocess Communication and Authentication
for more information).
Unlike the ALI, ADI, CAPI, or AAPI languages this interchange has no
additional structure,
there are no phases (eg: no command, ack, or data phases).
Open Issues
None known at this time.
Functional Specification
Command Descriptions
| hello |
The hello command
is designed to implement a language and language version negotiation scheme.
An external client will use the hello command to announce itself
to the MLM Core.
It will include in that command
the name of the language it would like to speak,
a list of the different version numbers of that language that it supports,
a name for itself as an application,
and a name for itself as a particular instance of an application.
LCPs and DCPs will use the OpenVault name of the device that they
control as their application name. |
welcome |
The welcome command
is designed to tell the client which version of the given language
the MLM Core has decided to use when talking to that client.
After the external client has announced itself to the MLM Core
via an appropriately filled in hello command,
the MLM Core will respond with a welcome command.
That command will specify which of the language versions named in
the hello command the MLM Core will be using during this session.
|
unwelcome |
The unwelcome command
is designed to tell the client that none of the combinations of language
and language version it provided are supported by this MLM Core.
After the external client has announced itself to the MLM Core
via a hello command,
the MLM Core may respond with an unwelcome command
if the language name is unknown or none of the language versions
supported by the client are supported by the MLM Core.
There is both a machine-understandable error token
and a set of text strings to display for the user.
|
Element Descriptions
| language |
A language name is the name of the language that the client
would like to use when talking to the MLM Core.
It can (currently) be one of the following: "ALI", "ADI", "CAPI", or "AAPI".
|
versions |
A version number is a string identifying a particular revision
of the named language.
A hello command can specify multiple versions, meaning that the
client is prepared to speak any of the named versions with the MLM Core.
Examples of version numbers include: "1", "1.0", and "2.1".
|
client |
A client name is a text string that tells the MLM Core
the application's name; an example might be "NetWorker".
LCPs and DCPs will use the OpenVault name of the device that they
control as their client name.
An LCP example might be "robbie" while a DCP example might be "firstDLT"
and a PROXY example might be "fileserver1".
|
instance |
An instance clause is a text string that tells the MLM Core the
name of the particular occurrence of the application.
For example, if the application name were "NetWorker", the instance name
might be the name of the host it is running on or the name of the
department being backed up.
Another example might be a system with two possible connections
to a high-speed tape drive that would like to run a separate DCP
for each of those connections.
Each DCP would have a client of the drive name,
but each would have a different instance name so that
the core could tell them apart.
|
error token |
This is part of an unwelcome response from the MLM Core.
An error token is one of a set of predefined text strings
corresponding to the error that occurred.
For example: "EBADLANGUAGE" or "EBADVERSION".
|
error text string |
This is part of an unwelcome response from the MLM Core.
An error text string is a free format text string that expresses
the same error shown in the error token in a human-readable format.
For example: "The language name is not recognized".
|
Language Syntax Specification
Syntactic conventions are that single quotes may be used
in place of double quotes in all contexts.
HELLO Command Syntax
This syntax is used by the external client when initiating a
connection to the MLM Core.
The WELCOME syntax is detailed later and
is used when the MLM Cores is responding to the external client.
helloStmt: "hello" <helloArgs>+ ";"
helloArgs: <helloLangSpec>|<helloVersionSpec>|
<helloClientSpec>|<helloInstanceSpec>
helloLangSpec: "language" "[" <SHORTSTRING
(languageName)> "]"
helloVersionSpec: "versions" "[" <SHORTSTRING
(versionNumber)>+ "]"
helloClientSpec: "client" "[" <SHORTSTRING
(clientNameOrDeviceName)> "]"
helloInstanceSpec: "instance" "[" <SHORTSTRING
(instanceName)> "]"
HELLO Command Examples
hello language["CAPI"] versions["1.0" "2.0"] client["networker"]
instance["physics"];
A client is announcing itself as capable of talking either
version 1.0 or 2.0 of the CAPI language, the client application's
name is "networker", and this is instance "physics" of that
application.
hello language["ALI"] versions["2.0"] client["robbie"] instance["one"];
A client is announcing itself as capable of talking only version
2.0 of the ALI language (which make that client an LCP), the
client's name is "robbie" (which means that is controls a robot
named "robbie"), and this is instance "one" of that application.
WELCOME and UNWELCOME Command Syntax
This syntax is used by the MLM Core when it is responding to an
external client.
response: <welcomeStmt> | <unWelcomeStmt>
welcomeStmt: "welcome" "version" "[" <SHORTSTRING(versionNumber)> "]" ";"
unWelcomeStmt: "unwelcome" <unWelcomeArgs>+ ";"
unWelcomeArgs: "error" "[" <SHORTSTRING(errorToken)> "]" |
"text" "[" <STRING(text of message)> "]"
WELCOME and UNWELCOME Command Examples
welcome version["2.0"];
The MLM Core has agreed to talk version 2.0 of the specified
language.
unwelcome error["EBADLANG"];
The MLM Core did not recognize the language name and is
refusing to talk to the client.The socket will be closed
immediately after the unwelcome message.
unwelcome error["EBADVERSION"] text["Unsupported language version"];
The MLM Core does not support any of the versions of the
language named in the hello and is refusing to talk to
the client. The socket will be closed immediately after
the unwelcome message.
Possible Error Returns
If the MLM Core does not recognize the
language name,
or it does not support any of the specified the
versions
of that language, an
unwelcome response is issued and
the MLM Core will summarily close the socket.
