Envoy Module Installation Guide

Sushila Subramanian and Adam Saltsman
Internet2

Contents

•  Envoy Description
•  Current Tools
•  Prerequisites
•  Libraries
•  Certificates
•  Network Configuration
•  Installation
•  Download
•  Configuration
•  Setting up the auto-register cakebox features
•  Running Envoy
•  Test Setup

Envoy

The Envoy module is a part of the Pioneer system, designed and developed at Internet2, to provide a framework for some simple network performance tools. The goal of this project is to be able to use these cakeboxes at temporary locations such as conferences, online meeting end points, and so on, to determine the state of the network before attempting to use it for specific purposes such as a demo, or video-conference.

The rest of this document focuses on envoy installation. Please read the general installation instructions first before you try to install Envoy on your cakebox. You must be logged in as root to install Envoy on your system. There must be an entry for your machine on our LDAP server for this to work. Please contact sushila@umich.edu if you are installing a system from scratch rather than using one of our cakeboxes on loan, so we can make an addition to the required entries on our server. Please be warned that you are responsible for your own updates of Envoy software in this case.

Current Tools

Iperf
traceroute
pchar
ping

Iperf and traceroute are also available for a select set of Abilene nodes. All four are available between cakeboxes. The Pioneer Overview contains a basic overview of the types of measurements these tools provide within the Envoy framework.

Prerequisites

Libraries: Iperf assumes the existance of these libraries on the cakebox machine: /usr/lib/libstdc++-libc6.1-1.so.2 and /usr/lib/libstdc++-libc6.1-1.a.2. If these libraries have been replaced by newer ones, create a link to the newer library:
    % cd /usr/lib
    % ln -s libstdc++-libc6.2-2.so.3 libstdc++-libc6.1-1.so.2
    % ln -s libstdc++-libc6.2-2.a.3 libstdc++-libc6.1-1.a.2

Certificates: You must have a valid certificate in PEM format, called en.pem installed in the /pioneer/certs directory before Envoy will work.

Network Configuration: If you have a firewall installed, port 5000 must be opened up for messages back and forth. Your machine must have an IP address - either DHCP assigned, or static, and this IP address must be accessible through a DNS query.

Installation

Download: Envoy software modules are available here. This software distribution was last updated on 19 September 2002. To unpack, copy envoy.dist.tar.gz to /root and run the following commands:
    % gunzip envoy.dist.tar.gz
    % tar -xvpf envoy.dist.tar
This will create a pioneer directory under which the relevant files will be present. Remove the envoy.dist.tar file from the /root directory.

Configuration: The following files need to be edited before you can run envoy:

•  common.conf - Change directories to /root/pioneer/include. Edit this file only if its absolutely necessary that you use different values than the default. If you modify the envoy port value (my_en_port) to be something other than the default value, i.e. 5000, then it must be exactly the same as what has been entered into the LDAP database when the cakebox was rebooted, i.e. the value in the donotdelete.info file, in the root directory.
  
  This file also contains the names of certificates used for encrypted SSL connections between servers. In the first deployment of the cakeboxes, these machines will come with the appropriate certificates. Please ensure that anything in the /pioneer directory is root readable ONLY, in particular the /bin and /certs directories.
      % cd /root/pioneer
      % chown -fR root *
      % chmod -fR 771 *
  
•  ldap.info - Change directories again to /root/pioneer/include. This file has just two fields: ldap server, and ldap port. Make sure these point to the right Pioneer LDAP server.
  
•  cbmaild - Copy this file from the /init directory to /etc/init.d. Then use the chkconfig command to make sure it starts up on reboots.
      % cd /etc/init.d
      % chkconfig --add cbmaild
  
•  mailme.pl - Copy this file from the /init directory to your BASEDIR (usually /root on cakebox machines). Edit the previous file (cbmaild) and change BASEDIR (one occurance within the file) to be whatever the correct path is for this file, i.e. mailme.pl.
  
•  envoyd - Switch to /root/pioneer/init, and modify the BASEDIR environment variable to reflect the correct path. If you have been following this install document, BASEDIR should be changed to /root.
  There should be approximately 3 replacements. Make sure you also replace it in commented fields. Examples of where it should be replaced are The following lines:
      # config: BASEDIR/pioneer/include/common.conf
      # config: BASEDIR/sushi/pioneer/include/ldap.info
      cd BASEDIR/pioneer/envoy
  
  Copy this file to /etc/init.d. Use the chkconfig command to make sure it starts up on reboots.
      % cd /etc/init.d
      % chkconfig --add envoyd
  
  One must ensure that the envoyd start number (70 in the example) is higher than the phoneHome script start number (default 64; see the next section).

File Permissions: pchar, Iperf, and traceroute must all be owned by root and have the permissions, r-sr-xr-x set. Please ensure these are set correctly by doing an "ls -s" in the appropriate directory where these binaries are installed, and use chmod to correct permissions as necessary. To change permissions to the above value, do the following:
    % chmod u+s <binary-name>

We expect these binaries (or links to them) to exist at the following locations, for them to work through the pioneer interface:
    /usr/sbin/traceroute
    /bin/pig
    BASEDIR/pioneer/bin/pchar
    BASEDIR/pioneer/bin/iperf
 where: BASEDIR should be replaced with the directory where Envoy was installed (as you had done in the envoyd file.) Please do not use your version of Iperf, this is a modified version for Pioneer use.

Setting up the auto-register Cakebox features [This section may change soon]: Copy adminAddScript and phoneHome from /root/internet2 to /root, and run the following commands to make them executable:
From /root, run:
    % chmod 755 phoneHome
    % chmod 755 adminAddScript
This ensures that phoneHome and adminAddScript will be able to run during startup. Then, run the following commands:
    % cd /etc/init.d/
    % vi phoneHome
Now enter the following information:
    #!/bin/sh
    /root/phoneHome lookup.internet2.edu
Change the file permissions with the following command:
    % chmod 755 phoneHome
Use the chkconfig command to add phoneHome to the list of programs that are started on reboot:
    % cd /etc/init.d
    % chkconfig --add phoneHome
Then, run the adminAddScript with the following command line (this can be run from any directory):
    % /root/adminAddScript your.host.here
For example, here at Internet2, we run:
    % /root/adminAddScript lookup.internet2.edu

You should be given a series of prompts. Just follow the on-screen instructions;
    1. Type in the cakebox name you want (follow the example).
    2. Type in a very clear and specific description, and then enter your AdminUsername and password.
  This adds this cakebox to your LDAP server. It also writes a file in the cakebox's /root directory called donotdelete.info. Do not delete it! It contains important information that the phoneHome client uses to update the hub.

Your cakebox is ready! Now, every time it reboots it will update the server with its new IP address, and other properties as well.

To update or change any of the cakebox's ID, port number, or description, you must change the values in the donotdelete.info file that is on the cakebox. Be sure, if you modify the file, to delete any trailing space after the port number. This is important - the phoneHome program could fail if there is extra space following the port number.

Running Envoy: Shutdown the cakebox. Power it back up. Envoy and phoneHome should both be running at this point. Envoy can be manually run as well; from /etc/init.d, run the following command
    % envoyd <start | stop >
Running it manually should be unnecessary unless you are debugging or developing.

Test Setup: Go to http://envoy.internet2.edu/pioneer/en/. See if your machine appears in the menu (you may need to reload the page and it may take up to 30 minutes to appear on the menu).