Changeset 2b35261 for fedkit

Timestamp:

Feb 1, 2010 10:43:24 AM (14 years ago)

Author:

Ted Faber <faber@…>

Branches:

axis_example, compt_changes, info-ops, master, version-3.01, version-3.02

Children:

b73cc45

Parents:

2edec46

Message:

Initial docs

Location:

fedkit

Files:

• active_config.pl (modified) (1 diff)
• combo_active.pl (modified) (1 diff)
• gateway_lib.pm (modified) (13 diffs)
• prep_gateway.pl (modified) (2 diffs)

fedkit/active_config.pl

@@ -55 +55 @@
 $f->close();
 exit(0);
+
+=pod
+
+=head1 NAME
+
+B<active_config.pl> - Configure an active connectivity gateway under the DETER Federation Architecture
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<fedkit=>I<install_dir>
+
+Directory in which this software is installed.  Generally not needed.
+
+=item B<interfaces=>I<interface table>
+
+A list of interfaces to forward data on of the form:
+
+=begin text
+
+iface ip_addr
+
+=end text
+
+The interface is the operating system name of the interface and the IP address
+is given in standard dotted decimal notation.  Other characters on a line are
+ignored.
+
+=item B<peer=>I<hostname>
+
+The other gateway providing forwarding.
+
+=item B<perl=>I<perl_binary>
+ 
+Location of the perl binary.  Usually unneeded.
+
+=item B<ssh=>I<ssh_binary>
+
+The pathname of the ssh binary.  Unusally unnecessary.
+
+=item B<ssh_pubkey=>I<keyfile>
+
+A public to install as authorized.
+
+=item B<ssh_privkey=>I<identity_file>
+
+The identity to use for remote access
+
+=item B<tunnelip>
+
+True if the testbed uses the DETER tunnelip extension to provide external
+connectivity information
+
+=back
+
+=head1 SYNOPSIS
+
+B<active_config.pl> initiates the active side of the connectivity connection,
+which is to say that it:
+
+=over 4
+
+=item *
+
+Installs local keys and reconfigures that local ssh system to do link layer
+tunneling.
+
+=item *
+
+Starts a tunnel for each interface in the given interface table, both locally
+and remotely.
+
+=back
+
+=head1 AUTHORS
+
+Ted Faber <faber@isi.edu>
+
+=cut

fedkit/combo_active.pl

@@ -49 +49 @@
     "--ssh=$ssh $portparam");
 exit(20) if $?;
+
+=pod
+
+=head1 NAME
+
+B<combo_active.pl> - Do both the active configuration of a connectiveity gateway and service port forwarding.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<fedkit=>I<install_dir>
+
+Directory in which this software is installed.  Generally not needed.
+
+=item B<interfaces=>I<interface table>
+
+A list of interfaces to forward data on of the form:
+
+=begin text
+
+iface ip_addr
+
+=end text
+
+The interface is the operating system name of the interface and the IP address
+is given in standard dotted decimal notation.  Other characters on a line are
+ignored.
+
+=item B<peer=>I<hostname>
+
+The other gateway providing forwarding.
+
+=item B<perl=>I<perl_binary>
+ 
+Location of the perl binary.  Usually unneeded.
+
+=item B<port=>I<port_spec>
+
+Forward the given port.  The port is specified as 
+for B<port_forward.pl>
+
+=item B<ssh=>I<ssh_binary>
+
+The pathname of the ssh binary.  Unusally unnecessary.
+
+=item B<ssh_pubkey=>I<keyfile>
+
+A public to install as authorized.
+
+=item B<ssh_privkey=>I<identity_file>
+
+The identity to use for remote access
+
+=item B<tunnelip>
+
+True if the testbed uses the DETER tunnelip extension to provide external
+connectivity information
+
+=back
+
+=head1 SYNOPSIS
+
+Call B<active_config.pl> and B<port_forward.pl> with the relevant parameters.
+
+
+=head1 AUTHORS
+
+Ted Faber <faber@isi.edu>
+
+=cut

fedkit/gateway_lib.pm

@@ -3 +3 @@
 package gateway_lib;
 
+# Package stuff to keep the caller's namespace clean, but allow additions if
+# they need it.
 require Exporter;
 @ISA=qw(Exporter);
@@ -17 +19 @@
 use File::Copy;
 
+# Standard locations of these commands (FreeBSD)
 my $IFCONFIG = "/sbin/ifconfig";
 my $ROUTE = "/sbin/route";
@@ -22 +25 @@
 my $FINDIF = "/usr/local/etc/emulab/findif";
 
+# Takes an ssh config file and a reference to a hash of keys whose values must
+# be set a specific way.  Replaces existing entries with the set values.
 sub set_sshd_params {
     my($keys, $file) = @_;
@@ -44 +49 @@
 }
 
+# Append the given keyfile to the given authorised key file.
 sub import_key {
     my($keyfile, $authkeys) = @_;
@@ -57 +63 @@
 }
 
-
+# Keep trying to look up the given hostname until successful.  If timeout is
+# given, die after waiting that long.  If sleep is given, wait that many
+# seconds between attempts (defaults to 5).  
 sub wait_for_DNS {
-    my($name, $timeout) = @_;
+    my($name, $timeout, $sleep) = @_;
     my $start = time();
+    $sleep = 5 unless $sleep;
     my @rv;
 
@@ -67 +76 @@
         die "Timeout waiting for DNS to get $name\n" 
             if ($timeout && time() - $start > $timeout);
-    }
-}
-
+        sleep($sleep) unless @rv;
+    }
+}
+
+# Get the external access parameters (interface, address, netmask, mac address,
+# and next hop router) from tmcd in Emulabs that support the DETER tunnelip
+# extension.
 sub deter_tunnelip {
     # To parse tmcc
@@ -80 +93 @@
 
 
-    # Parse out the info about tunnelips
+    # Parse out the info about tunnelips.  Format is usually one line of
+    # ATTR=VALUE.  Multiple lines are possible.
     $tmcc->reader("$TMCC tunnelip");
     while (<$tmcc>) {
@@ -101 +115 @@
 }
 
+
+# Configure the given interface with the given IP address and netmask.
 sub configure_outgoing_iface {
-    my ($interface, $ip, $netmask, $mac) = @_;
+    my ($interface, $ip, $netmask) = @_;
 
     my @ifconfig = ($IFCONFIG, $interface, $ip);
@@ -111 +127 @@
 }
 
+# Add a route to the destination through the router.  If wait is given, do not
+# attempt to add the route until DNS has the hostname in it.  If timeout is
+# given, only wait that many seconds for DNS to acquire it.
 sub add_route {
     my($routedest, $router, $wait, $timeout) = @_;
@@ -138 +157 @@
 }
 
+# Connect the tap($tapno) interface to $iface at the link level.  Remove any IP
+# addresses assigned to interface to avoid confusing the routing system.  We're
+# very tolerant of errors as the bridge and other interfaces may already exist
+# when this is called.
 sub bind_tap_to_iface {
     my($tapno, $iface) = @_;
@@ -163 +186 @@
 }
 
+# Return the IP addresses accociated with this interface (as a list)
 sub iface_to_addr {
     my($iface) = @_;
@@ -176 +200 @@
 }
 
+# Return the interface that packets to this host (IP or DNS) would be sent on.
 sub dest_to_iface {
     my($dest) =@_;
@@ -193 +218 @@
 }
 
+# Return the interface bound to this IP address.  If there are more than one,
+# the first one returned by ifconfig is the one returned.
 sub addr_to_iface {
     my($addr) = @_;

fedkit/prep_gateway.pl

@@ -33 +33 @@
         gateway_lib::deter_tunnelip();
 
-    gateway_lib::configure_outgoing_iface($interface, $ip, $netmask, $mac);
+    gateway_lib::configure_outgoing_iface($interface, $ip, $netmask);
     # Add the route to a peer.  Wait up to an hour for the peer's IP address to
     # appear in the DNS.
@@ -40 +40 @@
 
 exit(0);
+
+=pod
+
+=head1 NAME
+
+B<prep_tunnel.pl> - Prepare a tunnel node for use as either a service or connectivity gateway.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<peer=>I<hostname>
+
+The other gateway providing forwarding.
+
+=item B<ssh_pubkey=>I<keyfile>
+
+A public to install as authorized.
+
+=item B<tunnelip>
+
+True if the testbed uses the DETER tunnelip extension to provide external
+connectivity information
+
+=back
+
+=head1 SYNOPSIS
+
+B<prep_gateway.pl> laods the necessary kernel modules for low-level bridging
+configures the local sshd to allow it, restarts that sshd, and installs the
+given key in root's authorized keys.
+
+If the gateway supports DETER gateway, it setablishes outside connectivity and
+adds a host rout to the given peer.
+
+=head1 AUTHORS
+
+Ted Faber <faber@isi.edu>
+
+=cut