Ubuntu Manpage: amsrc - CCSDS Asynchronous Message Service MIB initialization file

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

NAME

DESCRIPTION

CONTROL ELEMENTS

CONFIGURATION ELEMENTS

EXAMPLE

SEE ALSO