Provided by: ion_3.2.1+dfsg-1_amd64 bug

NAME

       amsrc - CCSDS Asynchronous Message Service MIB initialization file

DESCRIPTION

       The Management Information Base (MIB) for an AMS communicating entity (either amsd or an
       AMS application module) must contain enough information to enable the entity to initiate
       participation in AMS message exchange, such as the network location of the configuration
       server and the roles and message subjects defined for some venture.

       AMS entities automatically load their MIBs from initialization files at startup.  When AMS
       is built with the -DNOEXPAT compiler option set, the MIB initialization file must conform
       to the amsrc syntax described below; otherwise the expat XML parsing library must be
       linked into the AMS executable and the MIB initialization file must conform to the amsxml
       syntax described in amsxml(5).

       The MIB initialization file lists elements of MIB update information, each of which may
       have one or more attributes.  An element may also have sub-elements that are listed within
       the declaration of the parent element, and so on.

       The declaration of an element may occupy a single line of text in the MIB initialization
       file or may extend across multiple files.  A single-line element declaration is indicated
       by a '*' in the first character of the line.  The beginning of a multi-line element
       declaration is indicated by a '+' in the first character of the line, while the end of
       that declaration is indicated by a '-' in the first character of the line.  In every case,
       the type of element must be indicated by an element-type name beginning in the second
       character of the line and terminated by whitespace.  Every start-of-element line must be
       matched by a subsequent end-of-element line that precedes the start of any other element
       that is not a nested sub-element of this element.

       Attributes are represented by whitespace-terminated <name>=<value> expressions immediately
       following the element-type name on a '*' or '+' line.  An attribute value that contains
       whitespace must be enclosed within a pair of single-quote (') characters.

       Two types of elements are recognized in the MIB initialization file: control elements and
       configuration elements.  A control element establishes the update context within which the
       configuration elements nested within it are processed, while a configuration element
       declares values for one or more items of AMS configuration information in the MIB.

       Note that an aggregate configuration element (i.e., one which may contain other interior
       configuration elements; venture, for example) may be presented outside of any control
       element, simply to establish the context in which subsequent control elements are to be
       interpreted.

CONTROL ELEMENTS

       ams_mib_init
           Initializes an empty MIB.  This element must be declared prior to the declaration of
           any other element.

           Sub-elements: none

           Attributes:

           continuum_nbr
               Identifies the local continuum.

           ptsname
               Identifies the primary transport service for the continuum.  Valid values include
               "dgr" and "udp".

           pubkey
               This is the name of the public key used for validating the digital signatures of
               meta-AMS messages received from the configuration server for this continuum.  The
               value of this attribute (if present) must identify a key that has been loaded into
               the ION security database, nominally by ionsecadmin(1).

           privkey
               This is the name of the private key used for constructing the digital signatures
               of meta-AMS messages sent by the configuration server for this continuum.  This
               attribute should only be present in the MIB initialization file for amsd().  The
               value of this attribute (if present) must identify a key that has been loaded into
               the ION security database, nominally by ionsecadmin(1).

       ams_mib_add
           This element contains a list of configuration items that are to be added to the MIB.

       ams_mib_change
           This element contains a list of configuration items that are to be revised in the MIB.

       ams_mib_delete
           This element contains a list of configuration items that are to be deleted from the
           MIB.

CONFIGURATION ELEMENTS

       continuum
           Identifies a known remote continuum.

           Sub-elements: none

           Attributes:

           nbr Identifies the local continuum.

           name
               Identifies the local continuum.

           neighbor
               1 if the continuum is a neighbor of the local continuum, zero otherwise.

           desc
               A textual description of this continuum.

       csendpoint
           Identifies one of the network locations at which the configuration server may be
           reachable.  If the configuration server might be running at any one of several
           locations, the number of other locations that are preferred to this one is noted; in
           this case, csendpoints must be listed within the ams_mib_add element in descending
           order of preference, i.e., with the most preferred network location listed first.

           Sub-elements: none

           Attributes:

           epspec
               Identifies the endpoint at which the configuration server may be reachable.  The
               endpoint specification must conform the endpoint specification syntax defined for
               the continuum's primary transport service; see the AMS Blue Book for details.

           after
               If present, indicates the number of other configuration server network locations
               that are considered preferable to this one.  This attribute is used to ensure that
               csendpoints are listed in descending order of preference.

       amsendpoint
           Normally the specifications of the transport service endpoints at which an AMS
           application module can receive messages are computed automatically using standard
           transport-service-specific rules.  However, in some cases it might be necessary for a
           module to receive messages at one or more non-standard endpoints; in these cases,
           amsendpoint elements can be declared in order to override the standard endpoint
           specification rules.

           Sub-elements: none

           Attributes:

           tsname
               Identifies the transport service for which a non-standard endpoint specification
               is being supplied.

           epspec
               Identifies an endpoint at which the application module will be reachable, in the
               context of the named transport service.  The endpoint specification must conform
               the endpoint specification syntax defined for the named transport service; see the
               AMS Blue Book for details.

       application
           Identifies one of the applications supported within this continuum.

           Sub-elements: none

           Attributes:

           name
               Identifies the application.

           pubkey
               This is the name of the public key used for validating the digital signatures of
               meta-AMS messages received from the registrars for all cells of any message space
               in this continuum that is characterized by this application name.  The value of
               this attribute (if present) must identify a key that has been loaded into the ION
               security database, nominally by ionsecadmin(1).

           privkey
               This is the name of the private key used for constructing the digital signatures
               of meta-AMS messages sent by the registrars for all cells of any message space in
               this continuum that is characterized by this application name.  This attribute
               should only be present in the MIB initialization file for amsd().  The value of
               this attribute (if present) must identify a key that has been loaded into the ION
               security database, nominally by ionsecadmin(1).

       venture
           Identifies one of the ventures operating within the local continuum.

           Sub-elements: role, subject, unit, msgspace

           Attributes:

           nbr Identifies the venture.

           appname
               Identifies the application addressed by this venture.

           authname
               Identifies the authority under which the venture operates, distinguishing this
               venture from all other ventures that address the same application.

           gweid
               Identifies the RAMS network endpoint ID of the RAMS gateway module for this
               venture's message space in the local continuum.  Gateway endpoint ID is expressed
               as <protocol_name>@<eid_string> where protocol_name is either "bp" or "udp".  If
               protocol name is "bp" then eid_string must be a valid Bundle Protocol endpoint ID;
               otherwise, eid_string must be of the form <hostname>:<port_number>.  If the gweid
               attribute is omitted, the RAMS gateway module's RAMS network endpoint ID defaults
               to "bp@ipn:<local_continuum_number>.<venture_number>".

           net_config
               Has the value "tree" if the RAMS network supporting this venture is configured as
               a tree; otherwise "mesh", indicating that the RAMS network supporting this venture
               is configured as a mesh.

           root_cell_resync_period
               Indicates the number of seconds in the period on which resynchronization is
               performed for the root cell of this venture's message space in the local
               continuum.  If this attribute is omitted, resynchronization in that cell is
               disabled.

       role
           Identifies one of the functional roles in the venture that is the element that's
           currently being configured.

           Sub-elements: none

           Attributes:

           nbr Identifies the role.

           name
               Identifies the role.

           authname
               Identifies the authority under which the venture operates, distinguishing this
               venture from all other ventures that address the same application.

           pubkey
               This is the name of the public key used for validating the digital signatures of
               meta-AMS messages received from all application modules that register in this
               functional role.  The value of this attribute (if present) must identify a key
               that has been loaded into the ION security database, nominally by ionsecadmin(1).

           privkey
               This is the name of the private key used for constructing the digital signatures
               of meta-AMS messages sent by all application modules that register in this
               functional role.  This attribute should only be present in the MIB initialization
               file for application modules that register in this role.  The value of this
               attribute (if present) must identify a key that has been loaded into the ION
               security database, nominally by ionsecadmin(1).

       subject
           Identifies one of the subjects on which messages may be sent, within the venture that
           is the element that's currently being configured.

           Sub-elements: sender, receiver

           Attributes:

           nbr Identifies the subject.

           name
               Identifies the subject.

           desc
               A textual description of this message subject.

           symkey
               This is the name of the symmetric key used for both encrypting and decrypting the
               content of messages on this subject; if omitted, messages on this subject are not
               encrypted by AMS.  If authorized senders and receivers are defined for this
               subject, then this attribute should only be present in the MIB initialization file
               for application modules that register in roles that appear in the subject's lists
               of authorized senders and/or receivers.  The value of this attribute (if present)
               must identify a key that has been loaded into the ION security database, nominally
               by ionsecadmin(1).

           marshal
               This is the name associated with the content marshaling function defined for this
               message subject.  If present, whenever a message on this subject is issued the
               associated function is automatically called to convert the supplied content data
               to a platform-independent representation for transmission; this conversion occurs
               before any applicable content encryption is performed.  If omitted, content data
               are transmitted without conversion to a platform-independent representation.
               Marshaling functions are defined in the marshalRules table in the marshal.c source
               file.

           unmarshal
               This is the name associated with the content unmarshaling function defined for
               this message subject.  If present, whenever a message on this subject is received
               the associated function is automatically called to convert the transmitted content
               to local platform-specific representation; this conversion occurs after any
               applicable content decryption is performed.  If omitted, received content data are
               delivered without conversion to a local platform-specific representation.
               Unmarshaling functions are defined in the unmarshalRules table in the marshal.c
               source file.

       sender
           Identifies one of the roles in which application modules must register in order to be
           authorized senders of messages on the subject that is the element that's currently
           being configured.

           Sub-elements: none

           Attributes:

           name
               Identifies the sender.  The value of this attribute must be the name of a role
               that has been defined for the venture that is currently being configured.

       receiver
           Identifies one of the roles in which application modules must register in order to be
           authorized receivers of messages on the subject that is the element that's currently
           being configured.

           Sub-elements: none

           Attributes:

           name
               Identifies the receiver.  The value of this attribute must be the name of a role
               that has been defined for the venture that is currently being configured.

       unit
           Identifies one of the organizational units within the venture that is the element
           that's currently being configured.

           Sub-elements: none

           Attributes:

           nbr Identifies the venture.

           name
               Identifies the venture.

           resync_period
               Indicates the number of seconds in the period on which resynchronization is
               performed, for the cell of this venture's message space that is the portion of the
               indicated unit which resides in the local continuum.  If this attribute is
               omitted, resynchronization in that cell is disabled.

       msgspace
           Identifies one of the message spaces in remote continua that are encompassed by the
           venture that is the element that's currently being configured.

           Sub-elements: none

           Attributes:

           nbr Identifies the remote continuum within which the message space operates.

           gweid
               Identifies the RAMS network endpoint ID of the RAMS gateway module for this
               message space.  Gateway endpoint ID is expressed as <protocol_name>@<eid_string>
               where protocol_name is either "bp" or "udp".  If protocol name is "bp" then
               eid_string must be a valid Bundle Protocol endpoint ID; otherwise, eid_string must
               be of the form <hostname>:<port_number>.  If the gweid attribute is omitted, the
               RAMS network endpoint ID of the message space's RAMS gateway module defaults to
               "bp@ipn:<remote_continuum_number>.<venture_number>".

           symkey
               This is the name of the symmetric key used for both encrypting and decrypting all
               messages to and from modules in the remote message space that are forwarded
               between the local RAMS gateway server and modules in the local message space; if
               omitted, these messages are not encrypted.  The value of this attribute (if
               present) must identify a key that has been loaded into the ION security database,
               nominally by ionsecadmin(1).

EXAMPLE

       *ams_mib_init continuum_nbr=2 ptsname=dgr

       +ams_mib_add

       *continuum nbr=1 name=apl desc=APL

       *csendpoint epspec=beaumont.stepsoncats.com:2357

       *application name=amsdemo

       +venture nbr=1 appname=amsdemo authname=test

       *role nbr=2 name=shell

       *role nbr=3 name=log

       *role nbr=4 name=pitch

       *role nbr=5 name=catch

       *role nbr=6 name=benchs

       *role nbr=7 name=benchr

       *role nbr=96 name=amsd

       *role nbr=97 name=amsmib

       *role nbr=98 name=amsstop

       *subject nbr=1 name=text desc='ASCII text'

       *subject nbr=2 name=noise desc='more ASCII text'

       *subject nbr=3 name=bench desc='numbered msgs'

       *subject nbr=97 name=amsmib desc='MIB updates'

       *subject nbr=98 name=amsstop desc='shutdown'

       *unit nbr=1 name=orbiters

       *unit nbr=2 name=orbiters.near

       *unit nbr=3 name=orbiters.far

       *msgspace nbr=2

       -venture

       -ams_mib_add

SEE ALSO

       amsxml(5)