Delay-Tolerant Networking E. Birrane
Internet-Draft E. DiPietro
Intended status: Experimental D. Linko
Expires: January 3, 2019 Johns Hopkins Applied Physics Laboratory
July 2, 2018

Asynchronous Management Protocol Agent Application Data Model
draft-birrane-dtn-adm-agent-04

Abstract

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].

Status of This Memo

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 3, 2019.

Copyright Notice

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.


Table of Contents

1. Introduction

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.

1.1. Technical Notes

1.2. Scope

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.

1.3. Requirements Language

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.

2. Structure and Design of this ADM

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 a 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.

3. Naming and Identification

This section outlines the namespaces used to uniquely identify ADM objects in this specification.

3.1. Namespace and Nicknames

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.

Namespace Information
Identifier Value
Namespace Amp/Agent
ADM Enumeration 1

Given the above ADM enumeration, in accordance with [I-D.birrane-dtn-amp], the following AMP nicknames are defined.

Agent ADM Nicknames
Nickname Collection
20 Amp/Agent/Const
21 Amp/Agent/Ctrl
22 Amp/Agent/Edd
23 Amp/Agent/Mac
24 Amp/Agent/Oper
25 Amp/Agent/Rptt
27 Amp/Agent/Tblt
29 Amp/Agent/Var
30 Amp/Agent/Mdat
31-49 Amp/Agent/Reserved

4. AMP Agent ADM JSON Encoding

{
 "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"
   }
 ]
}
        
      

5. IANA Considerations

This document defines a moderated Namespace: "Amp/Agent" with the ADM enumeration of 0.

6. References

6.1. Informative References

[I-D.birrane-dtn-ama] Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-07, June 2018.

6.2. Normative References

[I-D.birrane-dtn-adm] Birrane, E., DiPietro, E. and D. Linko, "AMA Application Data Model", Internet-Draft draft-birrane-dtn-adm-02, June 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.

Authors' Addresses

Edward J. Birrane Johns Hopkins Applied Physics Laboratory EMail: Edward.Birrane@jhuapl.edu
Evana DiPietro Johns Hopkins Applied Physics Laboratory EMail: Evana.DiPietro@jhuapl.edu
David Linko Johns Hopkins Applied Physics Laboratory EMail: David.Linko@jhuapl.edu