# ----------------------------------------------------------------------------
#  $RCSfile: xbone-data-structure.txt,v $
#
# $Revision: 1.2 $
#   $Author: yushunwa $
#     $Date: 2003/02/28 02:01:22 $
#    $State: Exp $
# ----------------------------------------------------------------------------
#
# Primary Author: Yu-Shun Wang
# First Version:  2003/2/24
#
# ----------------------------------------------------------------------------

                          X-Bone Data Structure
                              Yu-Shun Wang

0.  Introduction

    This document lists all major internal data structures used by XBone.

    Note: The actual description of data structure follows a Perl-ish style
          with the notations of Perl hashes (%), arrays (@), etc.

1.  API Command Hash

  1.1  General Structure

    %API_Command = {

    # API Information

      protocol     => '1.5',      # protocol version
      release      => '2.0',      # release version
      credential   =>             # credential for the command issuer
      {
        auth_type  => 'x509',        # type of authentication
        user_email => 'yu@isi.edu',  # user email address
        user_name  => 'Yu-Shun Wang' # user name - canonical name
      },

    # Command Section

      command =>
      {
        # command type
          command => 'create_overlay',

        # command properties (command-dependent)
          prop1 => value1,
          prop2 => value2,
          ...

        # command object(s)
          overlay => name or description (XOL)

      }

    };

  1.2  Overlay Data Structure

    %master_overlay_list - a hash of all active overlays

    - $overlay_name => \%overlay_hash

    - %overlay_hash = {
      info => {
        overlay_name  => ovl_name,
        protocol      => 1.5,
        xol_protocol  => 2.0,
        release       => 2.1,
        credential    => {'auth_type'  => 'X509',
                          'user_email' => 'yushunwa\\@isi.edu',
                          'user_name'  => 'yushun' },
        level         => 0,
        retry         => 0, #-???-#
        search_radius => 5
      },

      classlist => {
        class_1 => { class_1 spec },
        class_2 => { class_2 spec },
        ...
      },

      main_overlay => {
        properites => {
          blah, blah, blah,
          etc.
        },
        nodes => {
          node1 => {
            properties => { ... },
            interfaces => { ... }  },
          meta2 => {
            properties => { ... },
            interfaces => { ... },
            links      => { ... },
            nodes      => { ... }  }
        },
        links => {
          link1 => { link1 spec },
          link2 => { link2 spec }
        },
        interfaces => { # exported ones
          interface1 => { iface spec },
          interface2 => { iface spec }
        }
      }
    };

    %Overlay = {

    # XOL Information

      xol_version => '1.1',    # XBone Overlay Language Version

    # List of classes (array)

      classes => [

      # class[0]
        {
          # class name
          class => 'line',

          # class properties (if any)

          class_prop1 => prop1,
          class_prop2 => prpo2,
          ...

          # network description of the class
          network => {

            # network properties (if any)
            network_prop1 => prop1,
            ...

            # node list, shouldn't this be an array?
            node_list => {

              node1 => {
                # node properties
                node_prop1 => prop1,
                ...
                # interface list
                interfaces => {
                  # interface properties: IPv4 or IPv6, etc.
                  # list of interfaces
                };
              },
              node2 => {
                ...
              },
              node3 => {
                ...
              }
            },

            # link list or net list
            link_list => [

              link1 => {
                # link end points
                name       => 'link1',
                node1      => 'node1',
                interface1 => 'interface1',
                node2      => 'node2',
                interface2 => 'interface2',

                # link properties
                bidirectional => 1|0,
                IPsec_auth    => ...,
                IPsec_encrypt => ...
              },
              link2 => { ... },
              link3 => { ... }
            ],

        },
      # class[1],
         .
         .
      ],

    # Root Definition / Top Level Overlay

      main_overlay => {
        props/summary,
        level,
        name,
        class,
        body{
          props/summary,
          nodes{
            node->{
              props/summary,
              interfaces,
              nodes,
              links,
            }
          },
          links,
          interfaces,
      }

    };

$VAR1 = {
  'info' => {
    'protocol' => '1.5',
    'search_radius' => '5',
    'xol_protocol' => '1.1',
    'release' => '2.0',
    'credential' => {
      'auth_type' => 'X509',
      'user_email' => 'yushunwa\\@isi.edu',
      'user_name' => 'yushun'
    }
  },
  'main_overlay' => {
    'body' => {
      'props' => {
        'IPsec_encryption' => 'none',
        'dns' => 'yes',
        'addresstype' => 'ipv4',
        'IPsec_authentication' => 'none',
        'dynamic_routing' => 'no'
      },
      'nodes' => {
        'host_0' => {
          'props' => {
            'class' => undef,
            'os' => 'freebsd'
          },
          'interfaces' => {
            'if_0' => undef
          },
          'body'
        },
        'host_3' => {
          'props' => {
            'class' => undef,
            'os' => 'freebsd'
          },
          'interfaces' => {
            'if_0' => undef
          }
        },
        'router_0' => {
          'props' => {
            'class' => undef,
            'os' => 'linux'
          },
          'interfaces' => {
            'if_0' => undef,
            'if_2' => undef,
            'if_1' => undef,
            'if_4' => undef,
            'if_3' => undef
          }
        },
        'host_4' => {
          'props' => {
            'class' => undef,
            'os' => 'freebsd'
          },
          'interfaces' => {
            'if_0' => undef
          }
        },
        'host_2' => {
          'props' => {
            'class' => undef,
            'os' => 'freebsd'
          },
          'interfaces' => {
            'if_0' => undef
          }
        },
        'host_1' => {
          'props' => {
            'class' => undef,
            'os' => 'freebsd'
          },
          'interfaces' => {
            'if_0' => undef
          }
        }
      },
      'links' => {
        'link_1' => {
          'right_node' => 'router_0',
          'left_node' => 'host_1',
          'left_if' => 'if_0',
          'link_name' => 'link_1',
          'right_if' => 'if_1'
        },
        'link_3' => {
          'right_node' => 'router_0',
          'left_node' => 'host_3',
          'left_if' => 'if_0',
          'link_name' => 'link_3',
          'right_if' => 'if_3'
        },
        'link_0' => {
          'right_node' => 'router_0',
          'left_node' => 'host_0',
          'left_if' => 'if_0',
          'link_name' => 'link_0',
          'right_if' => 'if_0'
        },
        'link_2' => {
          'right_node' => 'router_0',
          'left_node' => 'host_2',
          'left_if' => 'if_0',
          'link_name' => 'link_2',
          'right_if' => 'if_2'
        },
        'link_4' => {
          'right_node' => 'router_0',
          'left_node' => 'host_4',
          'left_if' => 'if_0',
          'link_name' => 'link_4',
          'right_if' => 'if_4'
        }
      }
    },
    'level' => 0,
    'summary' => {
      'IPsec' => '0',
      'router_os' => 'linux',
      'host_os' => 'freebsd',
      'routing' => 'static',
      'meta' => 0,
      'router' => 1,
      'host' => 5
    },
    'name' => 'test.xbone.net',
    'class' => 'star'
  },
  'class_list' => {
    'star' => {
      'network' => {
        'props' => {
          'IPsec_encryption' => 'none',
          'addresstype' => 'ipv4',
          'dns' => 'yes',
          'IPsec_authentication' => 'none',
          'dynamic_routing' => 'no'
        },
        'net_parts' => {
          'exportlist' => [],
          'netlist' => [
            {
              'right_node' => 'router_0',
              'left_node' => 'host_0',
              'link_name' => 'link_0',
              'left_if' => 'if_0',
              'right_if' => 'if_0'
            },
            {
              'right_node' => 'router_0',
              'left_node' => 'host_1',
              'link_name' => 'link_1',
              'left_if' => 'if_0',
              'right_if' => 'if_1'
            },
            {
              'right_node' => 'router_0',
              'left_node' => 'host_2',
              'link_name' => 'link_2',
              'left_if' => 'if_0',
              'right_if' => 'if_2'
            },
            {
              'right_node' => 'router_0',
              'left_node' => 'host_3',
              'link_name' => 'link_3',
              'left_if' => 'if_0',
              'right_if' => 'if_3'
            },
            {
              'right_node' => 'router_0',
              'left_node' => 'host_4',
              'link_name' => 'link_4',
              'left_if' => 'if_0',
              'right_if' => 'if_4'
            }
          ],
          'nodes' => {
            'router_0' => {
              'src_target' => 5,
              'interfaces' => {
                'if_0' => {
                  'used' => 1
                },
                'if_2' => {
                  'used' => 1
                },
                'if_1' => {
                  'used' => 1
                },
                'if_4' => {
                  'used' => 1
                },
                'if_3' => {
                  'used' => 1
                }
              },
              'props' => {
                'class' => undef,
                'os' => 'linux'
              },
              'dst_target' => 5
            },
            'host_3' => {
              'src_target' => 1,
              'interfaces' => {
                'if_0' => {
                  'used' => 1
                }
              },
              'props' => {
                'class' => undef,
                'os' => 'freebsd'
              },
              'dst_target' => 1
            },
            'host_0' => {
              'src_target' => 1,
              'interfaces' => {
                'if_0' => {
                  'used' => 1
                }
              },
              'props' => {
                'class' => undef,
                'os' => 'freebsd'
              },
              'dst_target' => 1
            },
            'host_4' => {
              'src_target' => 1,
              'interfaces' => {
                'if_0' => {
                  'used' => 1
                }
              },
              'props' => {
                'class' => undef,
                'os' => 'freebsd'
              },
              'dst_target' => 1
            },
            'host_2' => {
              'src_target' => 1,
              'interfaces' => {
                'if_0' => {
                  'used' => 1
                }
              },
              'props' => {
                'class' => undef,
                'os' => 'freebsd'
              },
              'dst_target' => 1
            },
            'host_1' => {
              'src_target' => 1,
              'interfaces' => {
                'if_0' => {
                  'used' => 1
                }
              },
              'props' => {
                'class' => undef,
                'os' => 'freebsd'
              },
              'dst_target' => 1
            }
          },
          'links' => {
            'link_1' => {
              'used' => 1
            },
            'link_3' => {
              'used' => 1
            },
            'link_0' => {
              'used' => 1
            },
            'link_2' => {
              'used' => 1
            },
            'link_4' => {
              'used' => 1
            }
          }
        }
      },
      'class' => 'star'
    }
  }
};


-- API Command ---------
%API_Command = {
  'protocol'   => '1.5',
  'release'    => '2.0',
  'credential' =>
   {
      'auth_type' => 'x509',
      'user_email' => 'yushunwa@isi.edu',
      'user_name' => 'Yu-Shun Wang'
   },
  'command' =>
   {
    'command'       => 'create_overlay',
    'search_radius' => '5',
    'xol_program'   => {
      'xol_protocol' => '1.1',
      'classes' => [
        {
          'class' => 'Testline',
          'network' => {
            'props' => {},
            'net_parts' => {
              'exportlist' => [],
              'netlist' => [
                {
                  'right_node' => 'b',
                  'left_node' => 'a',
                  'link_name' => 'link0',
                  'left_if' => 'right',
                  'right_if' => 'left'
                }
              ],
              'nodes' => {
                'a' => {
                  'src_target' => 1,
                  'interfaces' => {
                    'right' => {
                      'used' => 1
                    }
                  },
                  'props' => {
                    'class' => undef
                  },
                  'dst_target' => 1
                },
                'b' => {
                  'src_target' => 1,
                  'interfaces' => {
                    'left' => {
                      'used' => 1
                    }
                  },
                  'props' => {
                    'class' => undef
                  },
                  'dst_target' => 1
                }
              },
              'links' => {
                'link0' => {
                  'used' => 1
                }
              }
            }
          }
        }
      ],
      'directive' => {
        'class_name' => 'TestLine',
        'object_name' => 'foobar',
        'directive' => 'root'
      }
    }
  }
};