Scalable Simulation Framework
SSFNet 1.3 DML Reference

SSF.Net.Net whole model DML configuration
SSF.OS protocol DML configurations
SSF.Net component addressing
       topological NHI addressing
  CIDR hierarchy addresses
  IP addresses
  AS numbers
  implementation in SSFNet 1.1
things to know about DML and Net
The manual is presumably most useful when read together with the SSFNet source code distribution. The source code decides what is the correct interpretation if the tutorial is unclear. Please report errors to ato@renesys.com.

Standard SSFNet DML attributes

Reminder:
A DML schema specifies a concrete DML attribute tree by specifying key names, attribute value types, and the allowed number of attribute instances. Conveniently, DML schemas can be written using the DML syntax, where an attribute's value type and number of instances are represented by a formatting expression embedded in the DML Value of String type.

A keypath uniquely identifies an attribute in a schema tree (either internal or leaf) by a sequence of dot-separated keynames along the path from the root to the attribute. This is analogous to filesystem pathnames on Unix machines.

%[SFI]count (String, Float, Integer) specify leaf attribute value type and number of instances. A trailing ! after an integer count specifies that the count must be exact.

Consult the DML reference manual for information on DML syntax.

Standard configuration schema for class SSF.Net.Net

The general schema of a DML configuration file read by class SSF.Net.Net to instantiate a simulation is described below, attribute by attribute. It is an expanded version of the schema file SSFNet/examples/net.dml included in the SSFNet distribution.

A Net is a collection of Hosts, Routers, links and included Nets. Net inclusion is a powerful construct that permits to build very large models from "preconfigured subnetworks". Specification of included Nets, hosts and routers must contain either a single integer ID (id) or a range of contiguous, ascending integer IDs (idrange) but not both. The attribute idrange is used as a compact notation for an array of components. Relative to the immediately enclosing Net context the id and idrange values must all be distinct.

These integer identifiers are employed in the NHI component addressing method that permits to compose bigger networks from instances of Net without the need to re-number their internal components' ids.

Each Net component may be aligned to a symbolic alignment partition (or "timeline"). A component's alignment may differ from that of the enclosing Net. An SSF simulator executing on a multiprocessor machine will assign all components with the same alignment value to the same processor (thus they share the same simulated time value), while partitions with distinct alignment values may execute on distinct processors to exploit the available parallelism. If an alignment attribute is omitted, the enclosing component is assigned to the default alignment, thus if all alignment attributes are omitted then all simulation Entities execute on the same processor (serial execution) even if multiple CPUs are available.

schema fragment explanation
schemas [
  Net [
  
    frequency %I<1
Net is the top-level attribute enclosing the entire network configuration.

Net.frequency used only in toplevel Net sets the physical unit value of the smallest simulated time unit as the number (long int) of dimensionless simulator "ticks" per simulated second: thus in a simulation where at least one component requires a microsecond time resolution one would set the value as "frequency 1000000", and the simulated time resolution will be "one tick = one microsecond", that is the simulated time will advance by intervals measured in multiples of microseconds. See SSFNet Programming Guidelines for discussion.

    Net [
      id %I
      idrange [from %I1! to %I1!]
      alignment %S
      cidr %S 
      ip %S
      _extends .schemas.Net
    ]
Included Net, recursively defined by inheritance keyword _extends as having the same attribute tree as the toplevel Net (i.e., Net, host, router, link) in addition to explicitly specified attributes. Must contain either a single integer ID (id) (or a range of contiguous, ascending integer IDs (idrange) but not both). Relative to the immediately enclosing Net context the id and idrange values must all be distinct.

Optional attribute Net.cidr characterizes a hierarchical partition into CIDR IP address blocks within the enclosing Net context, see CIDR section.

Optional attribute Net.ip is a VLSM (variable length subnet mask) IP address of a network in a.b.c.d/p notation, see IP section.

    host [
      id %I
      idrange [from %I1! to %I1!]
      alignment %S

Net.host specifies a machine with a protocol graph installed, and zero or more configured network interfaces. (Net.router has identical attributes.)

Must contain either a single integer ID (id) (or a range of contiguous, ascending integer IDs (idrange) but not both). Relative to the immediately enclosing Net context the id and idrange values must be unique for each host and router.

      graph [
        description %S
        ProtocolSession [
          name %S1!
          use %S1!
        ]
      ]

Net.host.graph is an internal attribute specifying a list of protocols to be configured and the names of SSF.OS classes to use.

graph.description is an optional protocol graph description string,

ProtocolSession.name is a symbolic tag, like "tcp" or "ip", and ProtocolSession.use is the name of a class extending SSF.OS.ProtocolSession that will be installed. Use one ProtocolSession for each protocol.

      interface [
        id %I
        idrange [from %I1! to %I1!]
        ip %S 
      
        bitrate %F
        latency %F

        virtual %S
        

        queue   [ use %S ]
        buffer  %I

        monitor [ use %S ]

        tcpdump %S
        flaky   %F
      ]

Net.host.interface: configuration of network interface such as an Ethernet card. Must contain either a single integer ID (id) (or a range of contiguous, ascending integer IDs (idrange) but not both). Relative to the immediately enclosing host context the id and idrange values must be unique for each interface.

An interface that is not named in any link attribute is considered "down" - that is, unconnected.

Optional Net.host.ip in a.b.c.d/p notation, see IP section. If a host specification names multiple interfaces with interface.idrange and one interface.ip IP address attribute, each interface in the range consumes successive IP addresses, using the given IP attribute as the base address. In general, it is strongly recommended to avoid manually assigning IP addresses and to rely on automatically assigned addresses.

Attributes bitrate (bits per second) and latency (on-card latency in seconds), together describe the timing behavior of a stream of packets leaving the interface. If omitted, the default bitrate is 10 Mbs = 10,485,760 bps; and the default latency is 0.0001 sec.

If optional attribute virtual is "true", construct a virtual interface; if omitted virtual the default is "false".

Optional attribute queue names the queue manager class to use (in String %S), if omitted, the default queue class is SSF.Net.droptailQueue. Any addidional queue configuration attributes should be implemented as sub-attributes of queue.

Optional attribute buffer specifies the queue buffer size in bytes (as used by SSF.Net.droptailQueue). If not used, the default is unlimited buffer size.

Optional attribute monitor specifies to use class named in String %S for the queue monitor. A queue monitor must implement Java interface SSF.Net.PacketQueueMonitor. If omitted, no monitor is installed.

Optional attribute interface.tcpdump will 'tcpdump' all passing traffic into the named file; using class SSF.OS.binaryTcpDump. Optional attribute interface.flaky with float value P, 0.0<=P<=1.0, will cause interface instance to drop packets with the given probability P. The default value is 0.0.

      route [
        dest %S1! 
        interface %I<1
        next_hop %S<1
      ]
      
      nhi_route [
        dest %S1!
        interface %I<1
        next_hop %S<1
      ]
      
    ] # end of .schemas.Net.host

The attribute Net.host.route allows to manually specify a static route to remote network or host. For a host attached to a LAN it is mandatory to specify the route to the gateway router using dest default. Either route.interface or route.next_hop must be provided. If only route.interface is provided, the specified interface must be on a point-to-point link, so that the next hop is unique. If route.interface attaches to a link with two or more other interfaces, route.next_hop is mandatory if route.dest is not on this link.

Note two variants of static route specification, using either IP or NHI addressing.

The values of route.dest and route.next_hop are an IP address (in a.b.c.d/p notation) of destination host or network, and IP address of next hop, repectively.

The values of nhi_route.dest and nhi_route.next_hop are an NHI address of destination host or router interface, or Net, and NHI address of next hop interface, repectively.

In both variants the interface attribute is an integer interface ID to use in the host's context.

    router [
      _extends .schemas.Net.host
    ]

Syntactically, a router is synonymous with host, but it will usually have distinct protocols in its protocol graph, and optional configuration attributes required by OSPF or other routing protocols. The different roles of routers and hosts in a simulation warrant using different names.

    link [                            
      attach %S2
      delay %F
      alignment %S
      cidr %S
      ip %S
    ]

Net.link specifies a level 2 network connecting a set of attached host and/or router network interfaces. A link should be understood as a "link layer". It must have two or more link.attach attributes naming the attached network interfaces. Does not mandate what level 2 (i.e., link layer) routing or broadcast capabilities are present, or what symmetries of interface properties must exist (e.g., matching bitrates) -- that's left to the interfaces involved.

link.delay, with value in seconds, represents the contribution of the link itself to total transmission delay of an IP packet. It does not include interface-specific sources of delay such as NIC frame processing latencies or buffering (see Net.host.interface).

Attributes Net.link.cidr, and Net.link.ip are explained in the section on CIDR IP address blocking and section on IP address assignment, respectively. It is recommended not to use them and let SSF.Net.Net automatically allocate IP addresses unless you know what you are doing.

Attribute Net.link.alignment in SSFNet 1.1 causes different synchronization behavior for point-to-point links (class SSF.Net.ptpLinkLayer) and for LANs, i.e., links with three or more attached interfaces (class SSF.Net.lanLinkLayer). The former does not contribute to the multi-timeline synchronization, while the latter does (via the link delay attribute).

    randomstream [
      generator %S
      stream %S
      reproducibility_level %S
    ]

Net.randomstream attribute provides centralized control of the management and seeding of parallel random number streams, and degree of sharing of random number streams by consumers of the random numbers (i.e., RandomDistributions). This is critically important in a good quality simulation. Random numbers are needed by TCP to randomize the offsets of TCP timers and by other ProtocolSessions.

generator string is the name of a pseudorandom number generator distributed with SSFNet. The names you can choose are highest-quality generators "MersenneTwister" and "Ranlux" from packages cern.jet.random and edu.cornell.lassp.houle.RngPack distributed with SSFNet. You can also choose name "Java" (which is java.util.Random).

stream value is an arbitrary user-defined string. The seeds for the random number generators are formed from such a root string, concatenated with other SSFNet-provided strings, using the cryptographic message digest techniques (currently the MD5 function). Changing this root string automatically and deterministically changes the seeds in all instantiated generators.

reproducibility_level controls how many separate instances of a random number generator will be created in the running model, and how the output of these generators will be shared by various consumers of random numbers. The name "reproducibility_level" refers to the fact that with this attribute a user may either guarantee that the result of simulation will be exactly the same regardless of how many processors are used in a parallel simulation, or is willing to sacrifice that strict reproducibility for sake of performance (while all generators in SSFNet are fast, computing random numbers is not free and uses memory, and you may not want the penalty of having thousands of generator instances in a large model.)

The available string values of reproducibility_level in the order from most shared generators to least shared generators (one per instance of RandomDistribution) are:

  • timeline: all RandomDistributions instantiated in Entities aligned to a timeline share the same random number stream. Different timelines have independent and idependently seeded random number streams ( = generators). For a sequential execution (default, when no alignment attributes are used, as in this example) there will be just one instance of a named random number generator, whose output is shared by all instances of RandomDistributions (as said, in this tiny model they are buried in the TCP code).
  • host: all RandomDistributions instantiated in a Host share the same random number stream. Different Hosts have independent and idependently seeded random number streams ( = generators).
  • protocol: every instance of a ProtocolSession owns an independent random number stream. Different ProtocolSessions have independent and idependently seeded random number streams ( = generators).
  • distribution: every instance of a RandomDistributions owns an independent random number stream. Different RandomDistributions have independent and idependently seeded random number streams ( = generators).

See SSFNet/src/SSF/Util for the source code of random distributions. See the SSF.Net.Net source code for how the seeds are formed and distributed to individual generators.

    traffic [
      pattern [
        client %S1!
        servers [
          list %S
          nhi  %S
          nhi_range [from %S1! to %S1!]
          port %I1!
        ]
      ]
    ]
  
  ] # end of .schemas.Net
   
] # end of .schemas

Toplevel .Net.traffic attribute is used in SSFNet 1.1 and later to specify the global traffic scenarios for workload generation by client/server application level ProtocolSessions. All SSFNet 1.x application-level client protocols look up this attribute to find which servers they may connect to.

Used by classes SSF.OS.TCP.test.tcpClient, SSF.OS.UDP.test.udpStreamClient, SSF.OS.WWW.httpClient.

Within the traffic attribute, there may be an arbitrary number of pattern subattributes.

Within the pattern attribute, there must be a single client attribute, and one or more of servers attributes.

Each pattern specifies:

  • client: The topological (NHI) address of a client host or a Net, beginning with the highest included Net NHI address. If it is a Net address, then it specifies all client hosts within this Net.
  • servers: Must contain the port number. Must contain either the nhi or nhi_range attribute, but not both. A single server address is shown in the following example:
    servers [nhi 3:5:1(0) port 80]
    
    Array variant nhi_range is allowed only to specify an ascending contiguous range of server host ids, all with the same NHI network prefix and the same interface number: e.g.
    servers [nhi_range [from 3:5:1(0) to 3:5:12(0)] port 80]
    
    is a legal expression for an array of 12 servers.

Each pattern may have many servers, and it is up to the client implementation which servers it will choose and at which times.

The optional attribute servers.list introduced in ssfnet_1.3 can be matched by tcpClient or httpClient attribute server_list to narrow down a list of servers, and - more importantly - to allow a client application to distinguish multiple servers on a single host (Note that tcpClient and httpClient configuration does not specify the server port number; instead a client searches the list of all servers in the .Net.traffic attribute, and chooses the ones that match the client's host NHI address and - if present - also match the server_list string.

SSF.OS protocol DML configurations

You should first read the tutorial on SSF.OS and protocol design.

Each contributed protocol (such as TCP, BGP4, OSPF, and various client/server application level protocols) may define its own DML configuration attribute tree.

Protocol configuration attributes are read by a class extending ProtocolSession by its method

    public void config(Configuration cfg) throws configException
that overloads the corresponding method of the SSF.OS.ProtocolSession.

In contrast to the rather stable SSF.Net.Net configuration, users keep adding new protocols and new versions of already distributed protocols. Their DML configuration files may change more often, so consult the latest releases for up-to-date DML configuration files.

Here we include the SSFNet release 1.1 DML configuration file standards for SSF.OS.TCP, SSF.OS.UDP, SSF.OS.BGP, SSF.OS.OSPF, and generic network traffic DML specifications that are implemented for various client/server implementations included in SSFNet 1.1 release.

The protocol DML configurations may appear in various places in user-defined DML files, depending on whether each host has a distinct protocol configuration (then there would be one protocol configuration attribute per host); or a group of hosts have the same protocol configuration (then usually, but not necessarily, they appear under the toplevel .dictionary attribute), see the examples included in the SSFNet release.

Standard configuration schema for class SSF.OS.IP
schema fragment explanation
ProtocolSession [for ip use SSF.OS.IP
  debug   %S

  tiebreaker [
    use   %S
  ]

  monitor [
    use   %S
  ]
]

The value of optional attribute debug is "true" or "false", if "true" print verbose diagnostics; default is "false"

Attribute tiebreaker.use names the class implementing the Java interface SSF.Net.RouteTieBreaker that should be loaded to choose among routes of equal cost. If tiebreaker is omitted, the default is a simple hash on src and dest addresses provided in an anonymous inner class in SSF.Net.RadixTreeRoutingTable.

Optional attribute monitor specifies to use class named in String %S for the packet or flow monitor. A packet monitor must implement Java interface SSF.OS.IpMonitor. If omitted, no monitor is installed.

Standard configuration schema for class SSF.OS.TCP.tcpSessionMaster
schema fragment explanation
ProtocolSession [name tcp use SSF.OS.TCP.tcpSessionMaster
  tcpinit[
    ISS %I                  # initial sequence number
    MSS %I                  # maximum segment size
    RcvWndSize  %I          # receive buffer size in units of MSS
    SendWndSize %I          # maximum send window size in units of MSS
    SendBufferSize %I       # send buffer size in units of MSS
    MaxRexmitTimes %I       # maximum number of retransmission times 
    TCP_SLOW_INTERVAL %F    # granularity of TCP slow timer, sec
    TCP_FAST_INTERVAL %F    # granularity of TCP fast(delay-ack), sec
    MSL %F                  # maximum segment lifetime, sec
    MaxIdleTime %F          # maximum idle time, sec
    delayed_ack %F          # delayed ack option, true or false
    fast_recovery %S        # use fast recovery algorithm, true/false 
    show_report %S          # print summary connection report, true/false
  ]

  debug    %S            # if true, dump verbose TCP diagnostics to files
                         # for session & host (see below), true/false

  # dump filename prefixes - actual filenames end with "_hostID_flowID.out"
  # for session info, and with "_hostID.out" for host info

  rttdump   %S              # rtt dumpfile prefix  (session)
  cwnddump  %S              # cwnd dumpfile prefix (session)
  rexdump   %S              # rexmit timer dumpfile prefix (session)
  eventdump %S              # dumpfile prefix for all events (session)
  con_count %S              # dumpfile prefix for number of connections (host)
  rto_count %S              # dumpfile prefix for timeout info (host)
]
See SSF.OS.TCP documentation and validation pages for detailed explanations.
Standard configuration schema for class SSF.OS.UDP.udpSessionMaster
schema fragment explanation
ProtocolSession [name udp use SSF.OS.UDP.udpSessionMaster
  udpinit[
    max_datagram_size %I    # maximum UDP datagram payload size (bytes)
    debug %S                # verbose UDP session diagnostics, true/false
  ]
]
See method config() in class SSF.OS.UDP.udpSessionMaster.
Standard configuration schema for class SSF.OS.BGP4.BGPSession
schema fragment explanation

ProtocolSession [ name bgp  use SSF.OS.BGP4.BGPSession

  # Choice to configure BGP "automatically", using default rules.
  # If omitted, the value of autoconfig is 'true'.
  # If the value of autoconfig is `true', then absolutely no other
  # configuration of the BGP protocol session may be done
  # (any other attributes will be ignored).
  # On the other hand, if the value of autoconfig is `false',
  # then every other mandatory attribute must be explicitly
  # configured, or else an error will be flagged.

  autoconfig %S         # (true|false)

  # Two timers are set on a per-BGP speaker basis:

  connretry_time   %I1! # Connect Retry Interval,  seconds
  min_as_orig_time %I1! # Minimum AS Origination Interval, sec

  # whether this BGP speaker is a route reflector

  reflector %S    #(true|false)

  # any number of neighbors

  neighbor [

    # The `as' attribute must be the NHI prefix address of this
    # neighbor's AS, i.e. the global id of the Net which is
    # the AS boundary for this neighbor.  If it is identical
    # to the NHI prefix of the local BGP speaker's AS, then
    # it is interpreted as an internal neighbor.
    # Otherwise, interpreted as an external neighbor.

    as %S1!

    # For an external neighbor, the `address' attribute must
    # be a NHI  interface address relative to the neighbor's AS.
    # For an internal neighbor it must be an NHI *host* address
    # relative to the local AS.

    address %S1!

    # This is the NHI interface address, relative to the local
    # AS, which the neighbor should use when sending messages
    # to the local BGP speaker. Often an internal peer will use
    # the address of a virtual (loopback) interface, while
    # an external peer will typically use the address of a
    # physical interface on a point-to-point link.

    use_return_address %S1!

    hold_time       %I1!  # Hold Timer Interval, seconds
    keep_alive_time %I1!  # Keep Alive Timer Interval, seconds
    min_adver_time  %I1!  # Minimum Route Advertisement
                          # Interval, seconds

    # The ibgp attribute is only meaningful if this is an internal
    # neighbor and if the local BGP speaker is itself a route
    # reflector.  If that is the case, then this attribute indicates
    # that this neighbor is either a reflector or client in the same
    # IBGP cluster as the local BGP speaker.

    ibgp %S               # (reflector|client)

    # policy specifications:
    # exactly one inbound route filter:

    infilter [

      # any number of clauses (none => deny every route)

      clause [
        precedence %I1! # all clauses in the same rule must have
                        # unique values,
                        # starting at 1 and increasing incrementally

        predicate  [      # always exactly 1 pr clause

          # any number of atoms (none => match any route)
          atom [
            attribute %S1! # (origin|as_path|nhi_path|next_hop|med|
                           #  local_pref|atomic_agg|aggregator|
                           #  community|originator_id| cluster_list)
            matcher %S1!   # regular expr. for matching the attribute
          ]
        ]

        action [           # always exactly 1 pr clause
          # primary action to permit or deny a route
          primary %S1!     #  (permit|deny)

          # zero or more atoms
          atom [             # actions for path attribute manipulation
            attribute %S1!:  #  (origin|as_path|next_hop|med|local_pref|
                             #   atomic_agg|aggregator|
                             #   community|originator_id|cluster_list)

            type %S1!        #  (set|append|prepend) action to perform

            value %S         # one or more values used by the action
          ]
        ]
      ]  # end of clause
    ]  # end of bgp infilter rules

    # exactly one outbound route filter:

    outfilter [
        ... same attributes as for infilter,
        ... omitted for brevity
    ]

  ]  # end of neighbor

] # end of ProtocolSession

Class SSF.OS.BGP4.BGPSession:

Each individual BGP protocol session (BGP speaker) must be configured separately. That is, network attributes which apply to multiple BGP speakers simultaneously (such as IBGP clusters) must be configured individually at each speaker in such a way that they collectively define the network attribute, just as done in the real world. The configuration of an individual BGP speaker takes place within a ProtocolSession attribute (refer to the SSFNet schema, .schemas.Net.host.graph.ProtocolSession). Such a ProtocolSession attribute must have a subattribute name with a value of bgp as well as a subattribute use with a value of SSF.OS.BGP4.BGPSession.

autoconfig tells whether to configure BGP "automatically", using default rules. The default value of this attribute, should it be omitted, is 'true'. This greatly simplifies the DML code of models for which autoconfiguration is used. If the value of autoconfig is `true', then absolutely no other configuration of the BGP protocol session may be done (any other attributes will be ignored). On the other hand, if the value of autoconfig is `false', then every other attribute must be explicitly configured, or else an error will be flagged.

See the documentation included in the package SSF.OS.BGP4 for aditional explanation and latest additions/revisions.

Net [    # top-level Net enclosing the whole model
  ...

  Net [
    AS_status boundary
    ....

  ]

  bgpoptions [

    # Prints messages associated with the given
    # validation test.  This attribute is intended
    # only for the DML files of validation tests.

    validation_test %I

    # Minimum wait time, in seconds, at the beginning
    # of the simulation during which each BGP protocol
    # session is inactive.

    base_startup_wait %F

    # The upper bound on a range of time, in seconds,
    # to be used for adding jitter to the startup
    # wait period on a per-BGP protocol session
    # basis.  The lower bound of the range is always
    # 0.0.  Use 0.0 for no jitter.

    startup_jitter_bound %F

    # Use NHI addressing in debugging output.  This means
    # that AS numbers, IP prefixes and IP addresses will
    # be converted to their NHI address equivalents.
    use_nhi_addressing  %S          # (true|false)

    # show various identifying values for BGP routers
    show_id_data        %S          # (true|false)

    # show neighbor info for each BGP speaker
    show_nb_info        %S          # (true|false)

    # show the configuration of IBGP clusters
    show_ibgp_clusters  %S          # (true|false)

    # show manually (DML) configured BGP attributes
    show_timer_config   %S          # (true|false)

    # show jittered timer interval values at startup
    show_jitter         %S          # (true|false)

    # show when BGP Start events occur
    show_start_event    %S          # (true|false)

    # show when BGP Stop events occur
    show_stop_event     %S          # (true|false)

    # show when TransConnOpen events occur
    show_transopen      %S          # (true|false)

    # show when TransConnClose events occur
    show_transclose     %S          # (true|false)

    # show when TransConnOpenFail events occur
    show_transfail      %S          # (true|false)

    # show when TransFatalError events occur
    show_transfatal     %S          # (true|false)

    # show when peer connections are established
    show_conn_estab     %S          # (true|false)

    # show negotiated Hold Timer Interval values
    show_hold_value     %S          # (true|false)

    # show Keep Alive Timer Interval values in use
    show_ka_value       %S          # (true|false)

    # show when Open msgs are sent
    show_snd_open       %S          # (true|false)

    # show when Open msgs are received
    show_rcv_open       %S          # (true|false)

    # show when KeepAlive msgs are sent
    show_snd_ka         %S          # (true|false)

    # show when KeepAlive msgs are received
    show_rcv_ka         %S          # (true|false)

    # show when Update msgs are sent
    show_snd_update     %S          # (true|false)

    # show when Update msgs are received
    show_rcv_update     %S          # (true|false)

    # show when Notification msgs are sent
    show_snd_notif      %S          # (true|false)

    # show when Notification msgs are received
    show_rcv_notif      %S          # (true|false)

    # show when KeepAlive Timers are set
    show_set_ka         %S          # (true|false)

    # show when Hold Timers are set
    show_set_hold       %S          # (true|false)

    # show when MinAdver Timers are set
    show_set_minadver   %S          # (true|false)

    # show when KeepAlive Timers expire
    show_ka_exp         %S          # (true|false)

    # show when ConnectRetry Timers expire
    show_connretry_exp  %S          # (true|false)

    # show when Hold Timers expire
    show_hold_exp       %S          # (true|false)

    # show when MinAdver Timers expire
    show_minadver_exp   %S          # (true|false)

    # show steps in handle_update() execution
    show_handle_update  %S          # (true|false)

    # show when new routes are added to routing table
    show_added_route    %S          # (true|false)

    # show degree of preference whenever calculated
    show_dop_calc       %S          # (true|false)

    # show steps of Decision Process execution
    show_dec_proc       %S          # (true|false)

    # show when the external update process begins
    show_ext_update     %S          # (true|false)

    # show when routes are added to fwding table
    show_fwd_table_add  %S          # (true|false)

    # show when routes are removed from fwding table
    show_fwd_table_rmv  %S          # (true|false)

    # print fwd table each time BGP changes it
    show_fwd_tables     %S          # (true|false)

    # show msgs related to route aggregation
    show_aggregation    %S          # (true|false)

    # show when MinAdverTmr expires w/no msgs waiting
    show_no_msg_waiting %S          # (true|false)

    # show when BGP FSM state changes
    show_state_changes  %S          # (true|false)

    # show when notable Sockets events occur
    show_socket_events  %S          # (true|false)

    # show when route reflection is performed
    show_reflection     %S          # (true|false)

    # show inbound policy rule filtering messages
    show_in_policy      %S          # (true|false)

    # show outbound policy rule filtering messages
    show_out_policy     %S          # (true|false)

    # print the Adj-RIBs-In each time it changes
    show_ribs_in        %S          # (true|false)

    # print the Loc-RIB each time it changes
    show_loc_rib        %S          # (true|false)

    # print the Adj-RIBs-Out each time it changes
    show_ribs_out       %S        # (true|false)

    # dump Adj-RIBs-In at simulation end
    dump_ribs_in        %S        # (true|false)

    # dump Loc-RIB at simulation end
    dump_loc_rib        %S        # (true|false)

    # dump Adj-RIBs-Out at simulation end
    dump_ribs_out       %S        # (true|false)

    # dump the forwarding table at simulation end
    dump_fwd_tables     %S        # (true|false)

    # dump the stability state at simulation end
    dump_stability      %S        # (true|false)
  ]
]

Attribute AS_status boundary in an included Net signifies that it is a Net enclosing an Autonomous System.

Optional attribute .Net.bgpoptions in the top-level Net is used for diagnostic and informational purposes.

The bgpoptions attribute is a list of the DML attributes available for use as BGP debugging, validation, and output options. Their values never change the functional behavior of BGP itself. The bgpoptions attribute, if utilized, must be an immediate subattribute of the top-level `Net' attribute. The default value of each of the boolean BGP options is `false'.

Standard configuration schema for class SSF.OS.OSPF.sOSPF
schema fragment explanation
Net [
  ...
  
  ospfoptions [
    show_ifaces      %S  # show ospf interface data structure
    show_AS_area     %S  # show AS and area number
    show_rtr_type    %S  # show router types
    show_hello_pkts  %S  # show hello packets and link connection
    show_lsas        %S  # show lsa packets
    show_lsdb        %S  # show link state databases
    show_rtg_tbl     %S  # show routing tables
  ]
  
  Net [
    ospf_area %I
    ....

  ]
]

Optional attribute .Net.ospfoptions in the top-level Net is used solely for debugging and informational purposes. All its subattributes have value "true" or "false", and control the printing of diagnostics.

Attribute ospf_area in an included Net signifies that it encloses an OSPF area. Release sOSPF_0.0.18 supports only one area 0 (backbone) and an ospf_area attribute must appear together in the same Net where an AS_status attribute appears. Thus currently we use OSPF as an internal routing protocol within each AS:

Net [
  AS_status boundary
  ospf_area 0
  ...
]
    
This limitation will be removed in a future release.
Standard configuration schema for classes SSF.OS.TCP.test.tcpClient, Server
schema fragment explanation
ProtocolSession [ name client use SSF.OS.TCP.test.tcpClient

  start_time 1.0          # earliest time to send request to server
  start_window 1.0        # send request to server at randomly chosen time
                          # in interval [start_time, start_time+start_window]
  file_size 10000000      # requested file size (payload bytes)
  request_size  4         # client request datagram size (bytes)
  show_report true        # print client-server session summary report
  debug false             # print verbose client/server diagnostics

  # new atributes in ssfnet_1.3 - backward compatible with ssfnet_1.2
  ------------------------------------------------------------------

  server_list  "mylist"   # identifies server list(s) name in traffic pattern
                          # if omitted concatenate all server lists in
                          # matching pattern

  # only one of either "file_size" or "random_file_size" must be used.
  # It is an error to specify both "file_size" or "random_file_size"
  # simultaneously.
  # Generated random variate interpreted as number of  payload bytes,
  # truncated to the integer value > 1.

  random_file_size [
    distribution [
      # distribution-dependent parameters are here.
      # see SSF.Util.Random.RandomStream for 21 distinct distributions
      name "Exponential"         # distribution class name
      lambda 0.001               # mean = 1/lambda
    ]
  ]

  # if both "off_time" and "random_off_time" are omitted,
  # client requests a file only once.
  # It is an error to specify both "off_time" and "random_off_time"
  # simultaneously.
  # An off_time (fixed or random) specifies client sleep time (seconds)
  # between completion of a file transfer request and the next request.

  # off_time 10.0                  # commented out because random_off_time
                                   # is specified in this example
  random_off_time  [
    distribution [
      name "Exponential"         # distribution class name
      lambda 0.01                # mean = 1/lambda
      # distribution-dependent params here...
    ]
  ]

  # If connection request times out or a connection is dropped
  # due to any error msg (peer reset, TCP abort, no route found, etc)
  # then the client may send a file request again as follows:
  # i) if "error_recovery" is omitted or "false", client suspends
  #    operation indefinitely (backward compatible with ssfnet1.2)
  # ii) if "error_recovery true", then:
  #    - if both "off_time" and "random_off_time" are omitted,
  #      client suspends operation indefinitely
  #    - if either "off_time" or "random_off_time" are specified,
  #      client will try connecting to the same server after
  #      a delay equal to the next value of "off_time".

  error_recovery true
]
          
ProtocolSession [
  name server use SSF.OS.TCP.test.tcpServer
  port 10                 # server's well known port

  client_limit  13        # max number of simultaneous established client
                          # connections, if omitted, default is unlimited.
                          # Connection requests arriving when limit is
                          # reached are dropped to time out.

  queue_limit   7         # maximum size of pending connection request
                          # queue, Qlimit, if omitted default is 5.
                          # Determines the total number of pending
                          # connection requests (see SSF.OS.TCP.tcpSocket).
                          # If exceeded, the listening socket sends RESET
                          # to client and drops the request.

  request_size  4         # client request datagram size (bytes)
  show_report true        # print client-server session summary report
  debug false             # print verbose client/server diagnostics
]
See method config() in classes SSF.OS.TCP.test.tcpClient, tcpServer.
Standard configuration schema for classes SSF.OS.UDP.test.udpStreamClient, Server
schema fragment explanation
ProtocolSession [ name client use SSF.OS.UDP.test.udpStreamClient

  start_time 1.0          # earliest time to send request to server
  start_window 1.0        # send request to server at randomly chosen time
                          # in interval [start_time, start_time+start_window]
  file_size 10000000      # requested file size (payload bytes)
  
  request_size  4         # client request datagram size (bytes)
  datagram_size 1000      # server datagram payload size (bytes)
  show_report true        # print client-server session summary report
  debug false             # print verbose client/server diagnostics
]
          
ProtocolSession [ name server use SSF.OS.UDP.test.udpStreamServer

  port 10                 # server's well known port
  client_limit  10        # max number of contemporaneously allowed clients
                          # if omitted, default is no limit
  request_size  4         # client request datagram size (bytes)
  datagram_size 1000      # server datagram payload size (bytes)
  send_interval 0.1       # time interval (in sec) between consecutive datagrams,
                          # if undefined, datagrams are sent back to back 
  show_report true        # print client-server session summary report
  debug false             # print verbose client/server diagnostics
]

Trivial example of a streaming server. See method config() in classes SSF.OS.UDP.test.udpStreamClient, udpStreamServer.

Standard configuration schema for classes SSF.OS.WWW.httpClient, Server
schema fragment explanation
ProtocolSession [name client use SSF.OS.WWW.httpClient

  # earliest time to send the first request to server (seconds).
  start_time 1.0
            
  # HTTP session arrival process in this client. The first session
  # begins at start_time + inter_session_time (in seconds).
  # Each session is with a server chosen uniformly at random from
  # the servers specified in the .Net.traffic for this client.
  inter_session_time [
    distribution [
      name "Exponential"         # distribution class name
      lambda 0.01                # mean = 1/lambda
    ]
  ]

  # distribution of number of pages per session with selected server.
  # if random variable = 0, round up to 1
  pages_in_session [
    distribution [
      name "Exponential"         # distribution class name
      lambda 0.2                 # mean = 1/lambda
    ]
  ]

  # distribution of user-think-times (off-times) between consecutive
  # in-session page requests, counted from the time when the previous
  # page delivery is completed (in seconds).
  inter_page_time [
    distribution [
      name "Pareto"              # distribution class name
      k 25.0                     # scale (cutoff) parameter
      alpha 2.0                  # shape (exponent) parameter
    ]
  ]

  # option to pipeline requests (i.e. send before waiting for 
  # completion of previous request
  # pipeline_requests false NOT IMPLEMENTED

  # distribution of delays between consecutive requests in a session.
  # If pipeline_requests = true, counted from the time of previous request;
  # If pipeline_requests = false, counted from the time when the previous
  # request was completed. (In seconds.)
  inter_request_time [
    distribution [
      name "Pareto"              # distribution class name
      k 0.1667                   # scale (cutoff) parameter
      alpha 1.5                  # shape (exponent) parameter
    ]
  ]
  
  http_hdr_size 1000    # nominal HTTP header size (virtual bytes)
                        # read from a socket before reading data
  persistent true       # true: one persistent TCP connection
                        # per session (HTTP1.1),
                        # false: one TCP connection for each
                        # request/response (HTTP1.0).
  show_report true      # print client-server session summary report
  debug false           # print verbose client/server diagnostics

  # new atributes in ssfnet_1.3 - backward compatible with ssfnet_1.2
  ------------------------------------------------------------------

  server_list  "mylist" # identifies server list(s) name in traffic pattern
                        # if omitted concatenate all server lists in
                        # matching pattern
]
See method config() in class SSF.OS.UDP.WWW.httpClient.
ProtocolSession [name server use SSF.OS.WWW.httpServer

  port 80            # server's HTTP port 
  client_limit  10   # max number of contemporaneously allowed clients
                     # if omitted, default is unlimited number

  # distribution of the number of objects in a page request:
  # if random variable = 0, round up to 1
  # NOTE: the response to page request contains the 1st object
  
  objects_in_page [
    distribution [
      name "Pareto"              # distribution class name
      k 0.6667                   # scale (cutoff) parameter
      alpha 1.2                  # shape (exponent) parameter
    ]
  ]

  # distribution of sizes of objects (in bytes)
  # if random variable = 0, round up to 1
  
  object_size [
    distribution [
      name "Pareto"              # distribution class name
      k 2000.0                   # scale (cutoff) parameter
      alpha 1.2                  # shape (exponent) parameter
    ]
  ]

  # distribution of server delays between request and response (in seconds)
  
  response_delay [
    distribution [
      name "Exponential"           # distribution class name
      lambda 0.01                  # mean = 1/lambda
    ]
  ]

  http_hdr_size 1000    # nominal HTTP header size (virtual bytes)
  show_report true      # print client-server session summary report
  debug false           # print verbose client/server diagnostics
]
See method config() in class SSF.OS.UDP.WWW.httpServer.

SSFNet component addressing

SSFNET supports multiple addressing and numbering schemes for networks, hosts/routers, and interfaces. The sections below describe their implementation in SSFNet 1.1.

Topological NHI addressing of Nets, Hosts, Interfaces n:n:n:h(i)

The basis of all addressing schemes is network topology, and in SSFNET, NHI (Net, Host, Interface) strings are the basic notation for identifying nodes and edges in the network graph.

Each Net, Host, Router, and NIC must either specify an integer ID (the id attribute) or an integer ID range (the idrange attribute). At a given level (e.g., within a given Net) the IDs and ID ranges of sub-Nets may not overlap; they need not be compact, however. The same is true of Hosts and Routers, and of NICs.

The global NHI address of a network is created by concatenating the ID of each network from the outermost to the innermost, separated by colons (":"). Similarly, the global NHI address of a host or router is created by concatenating the global NHI address of its containing network with the Host ID, separated by a colon. Finally, the NHI address of a NIC is created by adding the NIC ID, in parenthesis, to the containing Host NIC address.

For example, in this nested Net:

 Net [ id 3
   Net [id 7 
    Net [id 8
      Host [id 9 ...
            interface [id 2]
      ]
    ]
   ]
  ]

The outmost Net has NHI address 3, the next Net has address 3:7, and the innermost Net has address 3:7:8. The Host has NHI address 3:7:8:9, and the interface has NHI address 3:7:8:9(2).

NHI numbers are manually specified by the modeler's use of ID attributes. The ids have integer values that need not be sequentially assigned, although it is strongly recommended. The component link does not have the id attribute. The IDs are never automatically generated; omitting an id or idrange attribute at any level other than the topmost level is an error. As per the Net schema, the root Net should not have an id, idrange, or cidr address specified; only imported Nets acquire these.

The id attributes for Nets and for hosts and routers belong to the same address space, thus should be all distinct.

Within each host or router instance the interface.id integer values uniquely identify network interfaces.

The above definitions of id attributes permit to compose bigger networks from instances of Net without the need to re-number their internal components' ids.

Note that when a Net is included in another Net, each of its NHI identifiers simply acquires one more N: at the front of the N:N:...:N:H(I) string, when it is addressed from the importing Net. More examples:

Example 1: in the simplest case of a Net containing only hosts, routers and links, use H(I) only, e.g. 33(2) for host 33, interface 2.

Example 2: if a Net contains two Nets numbered 1, 2, then interface 1 on host 7 in Net 1 is 1:7(1), and interface 1 on host 7 in Net 2 is 2:7(1). The corresponding hosts are 1:7 and 2:7, respectively.

Example 3: If Net 1 in Example 2 is further composed of Nets numbered 1,2,3,4, then an interface belonging to lowest level Net 4 could be identified in the master Net as 1:4:98(12), or in words: interface 12 of router 98 in Net 4 in Net 1".

CIDR hierarchy addressing i/j/k/l

Each Link and Net (other than the root (toplevel) Net) in a DML model has associated with it a CIDR block address, consisting of 1 or more integers separated by slashes ("/"). If cidr attributes are entirely omitted, they will be automatically computed by SSF.Net.Net as follows: links and Nets are assigned CIDR block addresses relative to that of the Net in which they are defined, starting from CIDR block zero.

Simply speaking, cidr attributes specify a logical tree of subblocks of the toplevel IP address block allocated to a model. The values of cidr attributes are slash-separated integers similarly to a UNIX directory tree, and thus manually specified CIDR addresses may be multilevel: e.g., link [ cidr 1/2/4 ...] means "this network link shall get IP addresses from block 4 in block 2 in block 1". No two Nets or links may manually specify the same CIDR address; this is flagged as an error. In general, modelers should defer to the framework for automatic CIDR assignment unless they know what they're doing: It is easy to make errors, and that feature should be used with caution. The manually assigned CIDR attributes are not checked for consistency in SSFNet 1.x. In the future such checking may be a job for an offline design tool.

Read about Variable Length Subnet Mask IP address assignment, and see an example in a mini-tutorial on cidr attributes in DML networks.

IP addressing a.b.c.d/p

The SSFNet version 1.x supports Variable Length Subnet Mask (VLSM) IP address assignement method. The IP addresses may be allocated in either of three mutually exclusive ways:

Manually, using attributes Net.ip, Net.link.ip and Net.host.interface.ip, Net.router.interface.ip. Use with caution, as manually assigned IP addresses are not verified for consistency in this release. In the future this may be a job for an offline validation tool, not the general-purpose simulator.

Using the optional attributes Net.cidr and Net.link.cidr to guide the IP address assignement algorithm implemented in package SSF.Net.

Fully automatically if neither cidr nor ip attributes are provided.

Read about Variable Length Subnet Mask IP address assignment, and see an example in a mini-tutorial on cidr attributes in DML networks.

SSFNET 1.1 allows to assign only one IP address to a network interface. Future releases may allow multiple IP attributes, as in this example:

   interface [id 1 ip "10.0.0.0/32" ip "128.1.2.3/32" ....]

but the current code will not handle this correctly. It will complain up front because it expects to find a single value for "ip."

Autonomous Systems numbers

Net.AS_status

While not a full addressing scheme, SSFNet supports the automatic assignment of identifier numbers to autonomous systems. An included Net that specifies the AS_status boundary attribute specifies that it is the enclosing Net of an autonomous system, and is assigned the next free autonomous system number, starting from one. It's an error to specify that a Net is the root of an autonomous system if it is contained within another Net that is the root of an autonomous system.

SSFNet 1.1 implementation of addressing

The SSF.Net.Util.cidrBlock class implements NHI, CIDR, IP, and AS addressing, and provides convenience methods to translate among these addressing styles.

Currently the logic of SSF.Net is as follows: if you omit cidr attributes, it makes default cidr blocks automatically; if you omit ip attributes, it uses cidr (provided or computed) to make ip; if you supply ip, it ignores cidr if also provided.

SSF.Net.Util.cidrBlock now supports "strict" rules for CIDR and IP exclusion (all or nothing, mutual exclusivity). The SSFNet default behavior is "strict" when enforcing the rules about CIDR and IP manual assignment; the "-relax" flag to turn off strictness is a command line option. (Java SSF).

SSFNET enforces the rule that top-level Net may not define id, idrange, or cidr attributes.

Suppose a user specifies neither cidr nor ip attributes in the master Net file. Then each link within a Net is assigned an independent CIDR block (there is no default aggregation), each imported Net is assigned an independent CIDR block (there is no default aggregation); and the program will recursively count attached interfaces and find the minimum size of assigned cidr block that is sufficient to accomodate all interfaces. Sensible Net/subNet design is all that's needed to do reasonable network partitioning and address assignment, and first-time users may wish to stick to that basis.

Then if a user wishes to be clever, she will purposefully design recursive Net imports to achieve desired address aggregation. There is no need to ever specify CIDR attributes if Net import is used to build the desired CIDR nesting structure implicitly and automatically.

Tree Linkage

Each node in the cidrBlock tree represents one CIDR block, and contains three hashtables:

-- subblocks, mapping integers to corresponding CIDR sub-blocks

-- subnets, mapping integers to the CIDR blocks corresponding to the given NHI sub-net

-- interfaces, mapping NHI host/interface addresses (H(I)) to attachment specifications.

Note that the subnet tree is embedded within the subblock tree, derived by collapsing edges corresponding to 'placeholder' CIDR blocks. A placeholder CIDR block is created when the user manually specifies a multilevel CIDR address for a subnet.

For example, the following net:

 Net [
   Net [id 0 cidr 4]
   Net [id 1 cidr 5/1/4
     Net [id 8 cidr 3]
   ]
 ]

yields the following subblock tree:

   (-- (4) (5 (1 (4 (3)))))
and the following subnet tree:
   (-- (0) (      1 (8)))

Note that the subnets of the unnumbered root CIDR block correspond to the two sub-Nets with NHI addresses "0" and "1", omitting the CIDR placeholder blocks corresponding to the CIDR addresses "5" and "5/1".

Each cidrBlock B holds back-references to its CIDR parent and its NHI parent (CP.subblocks includes B, and NP.subnets includes B).

Construction

During construction of a cidrBlock, only the NHI address is considered, and the new block is entered into the subnets table of its parent.

After construction, the insertBlock method builds the CIDR address, entering the new block into the subblocks table of its parent (possibly introducing intermediate placeholder blocks if multilevel CIDR addresses have been manually specified).

Finally, one pass from the root determines the autonomous system numbers, another pass determines the IP address requirements, and a third pass performs IP address assignment to each net and interface. These later passes are skipped if the modeler supplies any manual IP attributes.

Interface summary at a glance

- see generated Javadocs in ssfnet/doc for details.

Important things about SSF.Net DML attributes

1. Important rule 1: How to verify the correctness of _extends and _find attribute values that use various user-defined DML tuples to specify a Net component:

The DML schema checker expands all _find and _extends attributes within an attribute value, and if the expansion agrees with the master schema for that attribute (optionally provided by the _schema attribute value) then all is OK.

2. Important rule 2: when a Net includes a Net, NOTHING gets rewritten in the imported DML Net tuple.

4. Note that Net.link does not have the id nor idrange attribute.

5. To attach a link to an imported Net's host or router, it must already have an unattached interface.

6. Cannot attach an interface to included Net's link (meant as a LAN) - it violates rule 2.

7. VLSM/CIDR partitions are imported with Nets. Only p2p links can cross Net boundaries, and may be associated with either Net's subdivision CIDR block.

8. In general, if you're not a power user, you should NOT be specifying IP routes. Always use NHI routes, because they are topologically defined and don't care about actual IP addresses. Remember that IP routes are not closed under Net inclusion. IP routes are almost always an overspecification that will prevent reuse of DML Net or host or router components.