Adding A Container to a Grid

The first part of this wiki is no longer valid. It explains how to setup a new container on a machine with the correct security settings to then attach it to the UVa Grid for an older Genesis build. For an explanation of the process of adding a container to the current (post 11/1/07) version of Genesis II, go to General network setup Similarly, one may want to hook two grids together in general with neither being the UVa grid. If both of the grids were started using the same build version of Genesis II and were bootstrapped, this is easily possible and explained in part two.

Attaching to UVa Grid

Estimated time for completion: 30 minutes

The UVa Grid has its own special VCGR Certificate Authority (CA). It also trusts the UVA Standard Assurance CA. The VCGR CA is used to create certificates for all hosts. Thus, to attach a container to the UVa Grid, we need the CA to create a certificate for it (Step 1.2). The new container must also be notified which trust stores it should trust. Thus the trusted.pfx file used by the UVa Grid must be acquired along with the admin certificate (Step 1.3). The configuration files of the new container must be modified to point to these new files (Step 1.4). Then the container can be attached to the net. Lastly, the security for the resources in the container must be configured (Step 1.7).

Step 1 : Install Latest Build

Install the latest Genesis II build on the machine where we are going to be starting the new container. The install .jar can be found at the Downloads section section of the website.

step 2 : Create Container Certificate/Keypair

We need to create a container certificate and keypair for the new container we are going to be adding. Ssh into centurion060 using the gbg account.

   >cd GeniiNet 

Run the following where $MACHINE is the URL for the machine for the new container along with the port that container will be using (i.e. if your new container resides on a cs machine called bob and will be using port 18080, this would be https://bob.cs.virginia.edu:18080)

   >"Genesis II/cert-tool" gen -dn="C=US, ST=Virginia, L=Charlottesville, O=UVA, OU=VCGR, CN=$MACHINE"
   -input-keystore=ca.pfx -input-keystore-pass=ca-password -input-alias="VCGR Certificate Authority" 
   -output-keystore=keys.pfx -output-keystore-pass=host-password -output-alias="VCGR Container"

This will create a keys.pfx file. Do not close this connection. We will need it in Step 6.

Step 3 : Copy Security Files

Copy the keys.pfx and admin.cer files along with the trusted.pfx file in the GeniiNet/Genesis II/security directory into the security folder of where the latest Genesis II build was installed (by default at C:\Program Files\Genesis II\security). Replace old files that had the same name.

Step 4 : Edit Server Config File

We need to edit the server-config.xml file. It is located in the configuration folder (by default at C:\Program Files\Genesis II\configuration).

Change Keystore Password

Search for key-password and key-store-password. Change the corresponding value of the password to what was specified in the script in Step 2 ie host-password. There will be two places where each of these need to be done.

Uncomment Admin.cer Property

Search for admin.cer. Uncomment this msconf:property. This specifies what X.509 identity is to be used when *new* resources are created. Note that previously there was no admin.cer file in the security folder.

Set Port Number

Make sure the port number you specified in the URL matches the port number specified in the config file. Search for port and change the value appropriately. By default, it is set to 18080.

Step 5 : Start Container

Once all the above security files/changes are in place, run the runContainer.bat file to start a new container (by default at C:\Program Files\Genesis II). You may want to run this from a command prompt to deal with any errors that arise. Otherwise the window will just close before you can view the errors. If everything goes successfully, you should see as the last line Container Started.

Step 6 : Attach New Host

Pull up the connection to centurion060. We will now connect to the existing UVa Grid and attach to the container we started in Step 5. To do this we need to login as admin. Select 0 when prompted.

   >cd Genesis\ II
   >./grid shell
   vcgr:$>login ../admin.pfx admin-password
   Please select a certificate to load:
       [0]:  CN=Administrator, OU=VCGR, O=UVA, L=Charlottesville, ST=Virginia, C=US
       [x]:  Cancel

Selection? 0

Now we can attach to the container. Here the URL is the same as we used before to specify the machine where the new container is running. NAME is what you want the new container to be called in RNS space on the UVa Grid.

   vcgr:$>attach-host {URL}/axis/services/VCGRContainerPortType /containers/{NAME}

Step 7 : Configure Container Security

Lastly we need to configure the security for the container we just added. We will run a script to do this but first the script must be edited to contain the correct new container name.

   vcgr:$>exit
   >cd ../..
   >sed 's/NAME/<NAME>/g' setContainerSecurity.xml > mySecurity.xml

Substitute the chosen name for the container from Step 6 for <NAME>. Once this is done, run the script in the grid.

    >cd GeniiNet/Genesis II
    >./grid script ../../mySecurity.xml

Attaching Bootstrapped Grids

If you want to connect two containers that are running the same version of Genesis II together into one grid, this can easily be accomplished if both containers have been bootstrapped.

In contrast to the procedure of attaching to the UVa Grid, in this case no manipulation of security credentials is required because both containers are bootstrapped using the same script which setups up identical and thus compatible certificate authorities and trust stores.

Step 1: Start Two Containers

If you have not yet installed Genesis II and started up two grids, you can do so by obtaining the latest GenesisII install .jar. Both containers must be running on the same version of Genesis II.

Step 2: Bootstrap Containers

Once you have a container and client running on each machine, bootstrap each container using the appropriate bootstrap script.

   >script deployments/DEPLOYMENT_TYPE/configuration/bootstrap.xml

STEP 3: Attach Containers

To attach container1 on machine1 to the grid of container2 on machine2, login to the net on machine2.

   >login deployments/DEPLOYMENT_TYPE/security/keys.pfx

Now we can attach container1. Here the URL specifies machine1 where container1 is running. NAME is what you want container1 to be called in RNS space on container2's grid. (i.e. If the container resides on a cs machine called bob and will be using port 18080, the URL would be https://bob.cs.virginia.edu:18080)

  >attach-host {URL}/axis/services/VCGRContainerPortType /containers/{NAME}