| Delay-Tolerant Networking | E. Birrane |
| Internet-Draft | E. DiPietro |
| Intended status: Experimental | D. Linko |
| Expires: January 1, 2019 | Johns Hopkins Applied Physics Laboratory |
| June 30, 2018 |
Asynchronous Management Protocol Agent Application Data Model
draft-birrane-dtn-adm-agent-03
This document describes an Application Data Model (ADM) for an Asynchronous Management Protocol (AMP) Agent. The AMP Agent represents a managed device in the Asynchronous Management Architecture. This document is in compliance with the template provided by [I-D.birrane-dtn-adm].
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 1, 2019.
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
An Application Data Model (ADM) provides a guaranteed interface for the management of an application or protocol in accordance with the Asynchronous Management Architecture (AMA) defined in [I-D.birrane-dtn-ama]. The ADM described in this document complies with the ADM Template provided in [I-D.birrane-dtn-adm] as encoded using the JSON syntax.
The AMP Agent ADM provides the set of information necessary to remotely manage agents in accordance with the Asynchronous Management Protocol (AMP) defined in [I-D.birrane-dtn-amp]. AMP provides a compact binary encoding of ADM objects and specifies a protocol for the exchange of those objects.
This ADM specifies those components of the Asynchronous Management Model (AMM) common to the management of any instance of any AMP Agent.
Any Manager software implementing this ADM MUST perform the responsibilities of an AMA Manager as outlined in [I-D.birrane-dtn-adm] as they relate to the objects included in this document.
Any Agent software implementing this ADM MUST perform the responsibilities of an AMA Agent as outlined in [I-D.birrane-dtn-adm] as they relate to the objects included in this document.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The AMP Agent ADM's structure is in accordance to [I-D.birrane-dtn-adm]. This ADM contains metadata, table templates, and controls, variables, report templates, macros, edd, and operators. The contents of this ADM are derived from the main functions and data that an agent needs to run AMP [I-D.birrane-dtn-amp].
The Metadata that is present in this document is common to all ADMs. All ADMs have metadata that includes the name, namespace, and version of the ADM as well as the name of the organization that is issuing that particular ADM. This is important for identification purposes of the ADMs and to ensure version control.
Because there are calculations done in various ADM objects that are needed for AMP, the operators that were chosen were ones that were the most common. For each of the most common operators, the only ones that were expressed in the document were ones that had the same input types and result types. This is to prevent an long list of operators that may never be used. The additional information provided in this ADM dealt with the number of known variables, macros, rules, controls and constants as well as the number of those instances that were running.
This section outlines the namespaces used to uniquely identify ADM objects in this specification.
In accordance with [I-D.birrane-dtn-adm], every ADM is assigned a moderated Namespace. In accordance with [I-D.birrane-dtn-amp], these namespaces may be enumerated for compactness. The namespace and ADM identification for these objects is defined as follows.
| Identifier | Value |
|---|---|
| Namespace | Amp/Agent |
| ADM Enumeration | 0 |
Given the above ADM enumeration, in accordance with [I-D.birrane-dtn-amp], the following AMP nicknames are defined.
| Nickname | Collection |
|---|---|
| 160 | Amp/Agent/mdat |
| 161 | Amp/Agent/edd |
| 162 | Amp/Agent/tblt |
| 163 | Amp/Agent/var |
| 164 | Amp/Agent/rptt |
| 165 | Amp/Agent/ctrl |
| 166 | Amp/Agent/mac |
| 167 | Amp/Agent/oper |
| 168 | Amp/Agent/const |
| 169-179 | Amp/Agent/Reserved |
{
"mdat": [
{
"name": "name",
"type": "STR",
"value": "AmpAgent",
"description": "The human-readable name of the ADM."
},
{
"name": "namespace",
"type": "STR",
"value": "Amp/Agent",
"description": "The namespace of the ADM."
},
{
"name": "version",
"type": "STR",
"value": "v3.0",
"description": "The version of the ADM."
},
{
"name": "organization",
"type": "STR",
"value": "JHUAPL",
"description": "The name of the issuing organization of the
ADM."
}
],
"edd": [
{
"name": "num_reports",
"type": "UINT",
"description": "This is the number of reports known to the
Agent."
},
{
"name": "sent_reports",
"type": "UINT",
"description": "This is the number of reports sent by the
agent."
},
{
"name": "num_tbr",
"type": "UINT",
"description": "This is the number of time-based rules
running on the agent."
},
{
"name": "run_tbr",
"type": "UINT",
"description": "This is the number of time-based rules run by
the agent since the last reset."
},
{
"name": "num_sbr",
"type": "UINT",
"description": "This is the number of state-based rules running
on the agent."
},
{
"name": "run_sbr",
"type": "UINT",
"description": "This is the number of state-based rules run by
the agent since the last reset."
},
{
"name": "num_const",
"type": "UINT",
"description": "This is the number of constants known by the
agent."
},
{
"name": "num_var",
"type": "UINT",
"description": "This is the number of variables known by the
agent."
},
{
"name": "num_macros",
"type": "UINT",
"description": "This is the number of macros known by the
agent."
},
{
"name": "run_macros",
"type": "UINT",
"description": "This is the number of macros run by the agent
since the last reset."
},
{
"name": "num_controls",
"type": "UINT",
"description": "This is the number of controls known by the
agent."
},
{
"name": "run_controls",
"type": "UINT",
"description": "This is the number of controls run by the
agent since the last reset."
},
{
"name": "cur_time",
"type": "TV",
"description": "This is the current system time."
}
],
"var": [
{
"name": "num_rules",
"type": "UINT",
"initializer": {
"type": "UINT",
"postfix-expr": [{
"ns":"Amp/Agent",
"nm":edd.num_tbr"
},{
"ns":"Amp/Agent",
"nm":"edd.num_sbr"
},{
"ns":"Amp/Agent",
"nm":"oper.plusUINT"
}]
},
"description": "This is the number of rules known to the Agent
(#TBR + #SBR)."
}
],
"Rptt": [
{
"name": "full_report",
"definition": [
{
"ns":"Amp/Agent",
"nm":"mdat.name"
},
{
"ns":"Amp/Agent",
"nm":"mdat.version"
},
{
"ns":"Amp/Agent",
"nm":"edd.num_reports"
},
{
"ns":"Amp/Agent",
"nm":"edd.sent_reports"
},
{
"ns":"Amp/Agent",
"nm":"edd.num_tbr"
},
{
"ns":"Amp/Agent",
"nm":"edd.num_sbr"
},
{
"ns":"Amp/Agent",
"nm":"edd.run_sbr"
},
{
"ns":"Amp/Agent",
"nm":"edd.num_const"
},
{
"ns":"Amp/Agent",
"nm":"edd.num_variables"
},
{
"ns":"Amp/Agent",
"nm":"edd.num_macros"
},
{
"ns":"Amp/Agent",
"nm":"edd.run_macros"
},
{
"ns":"Amp/Agent",
"nm":"edd.num_ctrl"
},
{
"ns":"Amp/Agent",
"nm":"edd.run_ctrl"
},
{
"ns":"Amp/Agent",
"nm":"var.num_rules"
}
],
"description": "This is all known meta-data, EDD, and VAR
values known by the agent."
}
],
"ctrl": [
{
"name": "list_adms",
"description": "This control causes the Agent to produce a
report entry detailing the name of each ADM
supported by the Agent."
},
{
"name": "add_var",
"parmspec": [
{"type":"ARI", "name":"id"},
{"type":"EXPR", "name":"def"},
{"type":"BYTE", "name":"type"},
{"type":"BYTE", "name":"flag"}
],
"description": "This control configures a new variable
definition on the Agent."
},
{
"name": "del_var",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control removes one or more variable
definitions from the Agent."
},
{
"name": "list_var",
"description": "This control produces a listing of every
variable identifier(ARI) known to the Agent."
},
{
"name": "desc_var",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control produces a detailed description
of one or more variable identifier(ARI)s known
to the Agent."
},
{
"name": "add_rptt",
"parmspec": [
{"type":"ARI", "name":"id"},
{"type":"AC", "name":"template"}
],
"description": "This control configures a new report template
definition on the Agent."
},
{
"name": "del_rptt",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control removes one or more report
template definitions from the Agent."
},
{
"name": "list_rptt",
"description": "This control produces a listing of every
report template identifier(ARI) known to
the Agent."
},
{
"name": "desc_rptt",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control produces a detailed description
of one or more report template identifier(ARI)
known to the Agent."
},
{
"name": "gen_rpts",
"parmspec": [
{"type":"AC", "name":"ids"},
{"type":"DC", "name":"rxmgrs"}
],
"description": "This control causes the Agent to produce a
report entry for each identified report
templates and send them to one or more
identified managers(ARIs)."
},
{
"name": "add_macro",
"parmspec": [
{"type":"STR", "name":"name"},
{"type":"ARI", "name":"id"},
{"type":"AC", "name":"def"}
],
"description": "This control configures a new macro definition
on the Agent."
},
{
"name": "del_macro",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control removes one or more macro
definitions from the Agent."
},
{
"name": "list_macro",
"description": "This control produces a listing of every macro
identifier(ARI) known to the Agent."
},
{
"name": "desc_macro",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control produces a detailed description
of one or more macro identifier(ARI) known to
the Agent."
},
{
"name": "add_tbr",
"parmspec": [
{"type":"ARI", "name":"id"},
{"type":"TV", "name":"start"},
{"type":"TV", "name":"period"},
{"type":"UVAST", "name":"count"},
{"type":"AC", "name":"action"},
{"type":"STR", "name":"description"}
],
"description": "This control configures a new time-based
rule(TBR) definition on the Agent."
},
{
"name": "del_tbr",
"parmspec": [
{"type":"AC","name":"ids"}
],
"description": "This control removes one or more TBR
definitions from the Agent."
},
{
"name": "list_tbr",
"description": "This control produces a listing of every
TBR identifier (ARI) known to the Agent."
},
{
"name": "desc_tbr",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control produces a detailed description
of one or more TRL identifier(ARI)s known to
the Agent."
},
{
"name": "add_sbr",
"parmspec": [
{"type":"ARI", "name":"id"},
{"type":"TV", "name":"start"},
{"type":"EXPR", "name":"state"},
{"type":"UVAST", "name":"count"},
{"type":"AC", "name":"action"},
{"type":"STR", "name":"description"}
],
"description": "This control configures a new state-based
rule(SBR) definition on the Agent."
},
{
"name": "del_sbr",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control removes one or more SBR
definitions from the Agent."
},
{
"name": "list_sbr",
"description": "This control produces a listing of every
macro identifier(ARI) known to the Agent."
},
{
"name": "desc_sbr",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control produces a detailed description
of one or more SBR identifier(ARI)s known to
the Agent."
},
{
"name": "store_var",
"parmspec": [
{"type":"AC", "name":"ids"}
],
"description": "This control stores variables."
},
{
"name": "reset_counts",
"description": "This control resets all Agent ADM
statistics reported in the Agent ADM report."
}
],
"const": [
{
"name": "amp_epoch",
"type":"TS",
"value": "2017-09-09T00:00:00Z",
"description": "This constant is the time epoch for the
Agent."
}
],
"mac": [
{
"name": "user_list",
"definition": [
{
"ns":"Amp/Agent",
"nm":"ctrl.list_vars"
},
{
"ns":"Amp/Agent",
"nm":"ctrl.list_rpt_tpl"
},
{
"ns":"Amp/Agent",
"nm":"ctrl.list_tbrs"
},
{
"ns":"Amp/Agent",
"nm":"ctrl.list_sbrs"
}
]
},
"description": "This macro lists all of the user defined
data."
}
],
"oper": [
{
"name": "plusINT",
"result-type": "INT",
"in-type": ["INT","INT"],
"description": "Int32 addition"
},
{
"name": "plusUINT",
"result-type": "UINT",
"in-type": ["UINT","UINT"],
"description": "Unsigned Int32 addition"
},
{
"name": "plusVAST",
"result-type": "VAST",
"in-type": ["VAST","VAST"],
"description": "Int64 addition"
},
{
"name": "plusUVAST",
"result-type": "UVAST",
"in-type": ["UVAST","UVAST"],
"description": "Unsigned Int64 addition"
},
{
"name": "plusREAL32",
"result-type": "REAL32",
"in-type": ["REAL32","REAL32"],
"description": "Real32 addition"
},
{
"name": "plusREAL64",
"result-type": "REAL64",
"in-type": ["REAL64","REAL64"],
"description": "Real64 addition"
},
{
"name": "minusINT",
"result-type": "INT",
"in-type": ["INT","INT"],
"description": "Int32 subtraction"
},
{
"name": "minusUINT",
"result-type": "UINT",
"in-type": ["UINT","UINT"],
"description": "Unsigned Int32 subtraction"
},
{
"name": "minusVAST",
"result-type": "VAST",
"in-type": ["VAST","VAST"],
"description": "Int64 subtraction"
},
{
"name": "minusUVAST",
"result-type": "UVAST",
"in-type": ["UVAST","UVAST"],
"description": "Unsigned Int64 subtraction"
},
{
"name": "minusREAL32",
"result-type": "REAL32",
"in-type": ["REAL32","REAL32"],
"description": "Real32 subtraction"
},
{
"name": "minusREAL64",
"result-type": "REAL64",
"in-type": ["REAL64","REAL64"],
"description": "Real64 subtraction"
},
{
"name": "multINT",
"result-type": "INT",
"in-type": ["INT","INT"],
"description": "Int32 multiplication"
},
{
"name": "multUINT",
"result-type": "UINT",
"in-type": ["UINT","UINT"],
"description": "Unsigned Int32 multiplication"
},
{
"name": "multVAST",
"result-type": "VAST",
"in-type": ["VAST","VAST"],
"description": "Int64 multiplication"
},
{
"name": "multUVAST",
"result-type": "UVAST",
"in-type": ["UVAST","UVAST"],
"description": "Unsigned Int64 multiplication"
},
{
"name": "multREAL32",
"result-type": "REAL32",
"in-type": ["REAL32","REAL32"],
"description": "Real32 multiplication"
},
{
"name": "multREAL64",
"result-type": "REAL64",
"in-type": ["REAL64","REAL64"],
"description": "Real64 multiplication"
},
{
"name": "divINT",
"result-type": "INT",
"in-type": ["INT","INT"],
"description": "Int32 division"
},
{
"name": "divUINT",
"result-type": "UINT",
"in-type": ["UINT","UINT"],
"description": "Unsigned Int32 division"
},
{
"name": "divVAST",
"result-type": "VAST",
"in-type": ["VAST","VAST"],
"description": "Int64 division"
},
{
"name": "divUVAST",
"result-type": "UVAST",
"in-type": ["UVAST","UVAST"],
"description": "Unsigned Int64 division"
},
{
"name": "divREAL32",
"result-type": "REAL32",
"in-type": ["REAL32","REAL32"],
"description": "Real32 division"
},
{
"name": "divREAL64",
"result-type": "REAL64",
"in-type": ["REAL64","REAL64"],
"description": "Real64 division"
},
{
"name": "modINT",
"result-type": "INT",
"in-type": ["INT","INT"],
"description": "Int32 modulus division"
},
{
"name": "modUINT",
"result-type": "UINT",
"in-type": ["UINT","UINT"],
"description": "Unsigned Int32 modulus division"
},
{
"name": "modVAST",
"result-type": "VAST",
"in-type": ["VAST","VAST"],
"description": "Int64 modulus division"
},
{
"name": "modUVAST",
"result-type": "UVAST",
"in-type": ["UVAST","UVAST"],
"description": "Unsigned Int64 modulus division"
},
{
"name": "modREAL32",
"result-type": "REAL32",
"in-type": ["REAL32","REAL32"],
"description": "Real32 modulus division"
},
{
"name": "modREAL64",
"result-type": "REAL64",
"in-type": ["REAL64","REAL64"],
"description": "Real64 modulus division"
},
{
"name": "expINT",
"result-type": "INT",
"in-type": ["INT","INT"],
"description": "Int32 exponentiation"
},
{
"name": "expUINT",
"result-type": "UINT",
"in-type": ["UINT","UINT"],
"description": "Unsigned int32 exponentiation"
},
{
"name": "expVAST",
"result-type": "VAST",
"in-type": ["VAST","VAST"],
"description": "Int64 exponentiation"
},
{
"name": "expUVAST",
"result-type": "UVAST",
"in-type": ["UVAST","UVAST"],
"description": "Unsigned Int64 exponentiation"
},
{
"name": "expREAL32",
"result-type": "REAL32",
"in-type": ["REAL32","REAL32"],
"description": "Real32 exponentiation"
},
{
"name": "expREAL64",
"result-type": "REAL64",
"in-type": ["REAL64","REAL64"],
"description": "Real64 exponentiation"
},
{
"name": "bitAND",
"result-type": "BYTESTR",
"in-type": ["BYTESTR","BYTESTR"],
"description": "Bitwise and"
},
{
"name": "bitOR",
"result-type": "BYTESTR",
"in-type": ["BYTESTR","BYTESTR"],
"description": "Bitwise or"
},
{
"name": "bitXOR",
"result-type": "BYTESTR",
"in-type": ["BYTESTR","BYTESTR"],
"description": "Bitwise xor"
},
{
"name": "bitNOT",
"result-type": "BYTESTR",
"in-type": ["BYTESTR"],
"description": "Bitwise not"
},
{
"name": "logAND",
"result-type": "BOOL",
"in-type": ["BOOL","BOOL"],
"description": "Logical and"
},
{
"name": "logOR",
"result-type": "BOOL",
"in-type": ["BOOL","BOOL"],
"description": "Logical or"
},
{
"name": "logNOT",
"result-type": "BOOL",
"in-type": ["BOOL"],
"description": "Logical not"
},
{
"name": "abs",
"result-type": "INT",
"in-type": ["UINT"],
"description": "absolute value"
},
{
"name": "lessTHAN",
"result-type": "BOOL",
"in-type": ["INT","INT"],
"description": "Less than"
},
{
"name": "greaterTHAN",
"result-type": "BOOL",
"in-type": ["INT","INT"],
"description": "Greater than"
},
{
"name": "lessEQUAL",
"result-type": "BOOL",
"in-type": ["INT","INT"],
"description": "Less than or equal to"
},
{
"name": "greaterEQUAL",
"result-type": "BOOL",
"in-type": ["INT","INT"],
"description": "Greater than or equal to"
},
{
"name": "notEQUAL",
"result-type": "BOOL",
"in-type": ["INT","INT"],
"description": "Not equal"
},
{
"name": "EQUAL",
"result-type": "BOOL",
"in-type": ["INT","INT"],
"description": "Equal to"
},
{
"name": "bitShiftLeft",
"result-type": "BYTESTR",
"in-type": ["BYTESTR","BYTESTR"],
"description": "Bitwise left shift"
},
{
"name": "bitShiftRight",
"result-type": "BYTESTR",
"in-type": ["BYTESTR","BYTESTR"],
"description": "Bitwise right shift"
},
{
"name": "STOR",
"result-type":"BYTESTR",
"in-type": ["BYTESTR","BYTESTR"],
"description": "Store value of parm 2 in parm 1"
}
]
}
This document defines a moderated Namespace: "Amp/Agent" with the ADM enumeration of 0.
| [I-D.birrane-dtn-ama] | Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-06, October 2017. |
| [I-D.birrane-dtn-adm] | Birrane, E., DiPietro, E. and D. Linko, "AMA Application Data Model", Internet-Draft draft-birrane-dtn-adm-01, March 2018. |
| [I-D.birrane-dtn-amp] | Birrane, E., "Asynchronous Management Protocol", Internet-Draft draft-birrane-dtn-amp-04, June 2018. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |