= 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 owamp 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 bwctl 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.
