= perfSONAR Mesh Configuration Install Instructions =

The perfSONAR-PS Mesh Configuration service allows the configuration of a
"mesh" of hosts so that they all perform the same set of tests with other hosts
in the mesh. This allows the deployment of disparate hosts while allowing
centralized control over them.

== Installation ==

Installation using YUM lets the package manager do the work of finding and
installing the dependencies.  The following command is all that is needed:

  (sudo) yum install perl-perfSONAR_PS-MeshConfig-Agent

There may be several prerequisites to install depending on the age of your
system.  To ensure that all are found, please be sure to install one of the
alternative repositories above. 

== Configuration ==

=== The Agent ===

  The agent is a script that downloads the mesh configuration file, generates a new
  configuration for the testing software, and (optionally) restarts the daemons. The
  script itself is located in
  /opt/perfsonar_ps/mesh_config/bin/generate_configuration .

  The script's configuration file is located at
  /opt/perfsonar_ps/mesh_config/etc/agent_configuration.conf . It will need to
  be modified to point to the URL with the mesh configuration file. There are a number of
  options that can be changed in this configuration file, but the only required
  change is to the mesh_configuration_url. The file itself is commented with
  descriptions of the various options.

  Once configured, the agent can be run manually, or by setting up a cron job
  to run it regularly. There is an example cron script in the 'scripts'
  directory of the software package. This script can be copied to /etc/cron.d
  directly, or modified as desired. The RPM installs this crontab entry by
  default.

  If you are running the agent on a pS-Performance Toolkit host, make sure that
  the "use_toolkit" and "restart_services" are enabled, and your configuration
  of the agent is done at this point. If not, continue on.

  There is one other modification that needs to be done before the agent is
  complete. The perfSONARBUOY measurement archive (used for the bwctl and owamp
  tests) has a password configured that must be shared between the agent and
  the measurement archives that the agent is storing data in. To configure the
  password, you'll need to edit
  /opt/perfsonar_ps/perfsonarbuoy_ma/etc/owmesh.conf . You'll need to add a
  variable "BWSecretName    BWPassword" and then add a variable "BWPassword"
  and set it to the password for the bwctl measurement archive. You'll also
  need to add "OWPSecretName    OWPPassword" and add a variable "OWPPassword"
  set to the password for the owamp measurement archive. For example, if the
  bwctl password was "bwctlp4ssw0rd" and the owamp password was
  "0w4mpp4ssw0rd", you'd add the following lines to the owmesh.conf.

    BWSecretName       BWPassword
    BWPassword         bwctlp4ssw0rd
    OWPSecretName      OWPPassword
    OWPPassword        0w4mpp4ssw0rd

=== The Measurement Archives ===

  Currently, the mesh configuration agent only updates the configuration for
  the testing hosts. The measurement archives need to already be configured to
  accept the results, and to make them available. These archives are configured
  by default on the Toolkit hosts, but need to be specially configured on
  non-Toolkit hosts.

=== perfSONARBUOY Measurement Archive ===

  If you are installing the agent on a Toolkit host, and the test results for
  the host will be stored on the host, you can skip this section.  Just remember
  that when building your mesh configuration, your bwctl archive will be
  available at:

    read_url:  http://[host]:8085/perfSONAR_PS/services/pSB
    write_url: [host]:8569

  The owamp archive should be available at:

    read_url: http://[host]:8085/perfSONAR_PS/services/pSB
    write_url: [host]:8570

  The perfSONARBUOY Archive can hold bwctl and owamp test results. To install
  the perfSONARBUOY Archive on your archive host, you'll need to install the
  'perl-perfSONAR_PS-perfSONARBUOY-server' package.

  After you have installed the perfSONARBUOY RPM, set the owamp and bwctl
  passwords using the method listed in the agent configuration section.

  You can edit the following variables in the owmesh.conf to set the following
  parameters.

    OWPCentralHost:     sets the address/port for the collector to listen on
    OWPCentralDBHost:   sets the database host (defaults to localhost) for owamp data
    OWPCentralDBPort:   sets the database port to use for owamp data
    OWPCentralDBName:   sets the database name to use for owamp data
    OWPCentralDBUser:   sets the database username to use for owamp data
    OWPCentralDBPass:   sets the database password to use for owamp data

    BWCentralHost:      sets the address/port for the collector to listen on
    BWCentralDBHost:    sets the database host (defaults to localhost) for bwctl data
    BWCentralDBPort:    sets the database port to use for bwctl data
    BWCentralDBName:    sets the database name to use for bwctl data
    BWCentralDBUser:    sets the database username to use for bwctl data
    BWCentralDBPass:    sets the database password to use for bwctl data

  After that, you can initialize the database by running:

    /opt/perfsonar_ps/perfsonarbuoy_ma/bin/bwdb -i root   # create the bwctl db
    /opt/perfsonar_ps/perfsonarbuoy_ma/bin/owdb -i root   # create the owamp db

    (note: the 'root' password it asks you for is the mysql root password
     which, on redhat machines, is generally left unset, so you can hit enter).

  You can start the bwctl collection service by running
  '/etc/init.d/perfsonarbuoy_bw_collector start', the owamp collection service
  by running '/etc/init.d/perfsonarbuoy_owp_collector start', and the read-only
  MA service by running '/etc/init.d/personarbuoy_ma start'. At this point,
  your bwctl archive should be available at:

    read_url:  http://[host]:8085/perfSONAR_PS/services/pSB
    write_url: [the value of BWCentralHost]

  The owamp archive should be available at:

    read_url: http://[host]:8085/perfSONAR_PS/services/pSB
    write_url: [the value of OWPCentralHost]

=== Traceroute Measurement Archive ===

  If you are installing the agent on a Toolkit host, and the test results for
  the host will be stored on the host, you can skip this section. Just remember
  that when building your mesh configuration, your archive will be available at:

    read_url: http://[host]:8086/perfSONAR_PS/services/tracerouteMA
    write_url: http://[host]:8086/perfSONAR_PS/services/tracerouteCollector

  The Traceroute Archive holds test results from regular traceroute tests. To
  install the Traceroute Archive on your archive host, you'll need to install
  the 'perl-perfSONAR_PS-TracerouteMA-server' package.

  After you have installed the Traceroute Archive RPM, edit
  /opt/perfsonar_ps/traceroute_ma/etc/owmesh.conf and configure the following
  variables.

    TRACECentralDBHost:   sets the database host (defaults to localhost) 
    TRACECentralDBPort:   sets the database port
    TRACECentralDBName:   sets the database name
    TRACECentralDBUser:   sets the database username
    TRACECentralDBPass:   sets the database password

  After that, you can initialize the database by running:

    /opt/perfsonar_ps/traceroute_ma/bin/tracedb -i root

    (note: the 'root' password it asks you for is the mysql root password
     which, on redhat machines, is generally left unset, so you can hit enter).

  You can start the services by running '/etc/init.d/traceroute_ma start'. At
  this point, your archive should be available at:

    read_url: http://[host]:8086/perfSONAR_PS/services/tracerouteMA
    write_url: http://[host]:8086/perfSONAR_PS/services/tracerouteCollector

=== PingER Measurement Archive ===

  PingER does not currently support centralized collection, so each host needs
  to have its own PingER archive. The default install via the Toolkit should
  setup a PingER database, and archive automatically.

  The PingER archive should be available at:

    read_url: http://[host]:8075/perfSONAR_PS/services/pinger/ma


=== The Mesh Configuration ===

  The mesh configuration is stored in a .json file that can be retrieved from a
  well-known URL. To ease the building of the .json, there is an included
  script "build_json". This script converts a config file in Config::General
  format into the appropriate .json. There is an commented example file located
  in "doc/example.conf".

  To use the build_json tool, you can run
  'build_json -input example.conf -output example.json'. This will convert the
  configuration file named example.conf into a json file named example.json.
  This file can then be placed into a well-known location to be downloaded by
  other agents.
