Version 59 (modified by, 10 years ago) (diff)



In order to participate in this tutorial you need to have an account at an InCommon institution. If you don't already have an account please follow [these instructions].

Make sure you know which institution will provide you access to GENI and the username and password you need to authenticate. If you don't know, please let us know.

Make sure that you have access to your email.

1. Create a GENI account

  1. Go to and press the Use GENI button
  2. From the Drop Down menu select your institutions. If you got an account through the GENI Identity Provider, please select GENI Project Office
    NOTE: Make sure that you do not choose the GENI Project Office (internal)
    Tip Start typing the name of your institution and see the list become smaller.
  3. You will be transferred in the Login Page of your institution. Fill in your username and password
  4. Complete the form that appears after you have successfully logged in and press Continue
  5. You will be transferred to an Activation Page. Make sure both checkboxes are checked and then press Activate

Congratulations, you have successfully created a GENI account.

2. Create a GENI Project

A GENI account has no priviledges outside of a Project, i.e. as long as you are not a member of a GENI Project you can not use any GENI resources. In GENI only Project Leads can create Projects. Any faculty member, or a person in a corresponding position in industry, can request to become a Project Lead and thus have the capability of creating GENI Projects.

Create a GENI Project
  1. In the first page of the portal, press the button Ask to be a Project Lead
  2. In the Modify Account page that showed up, fill in your telephone number; this is necessary for people that want to become Project Leads. Also check the box at the bottom of the page that says Make me a 'Project Lead' and press the Modify Account button.
  3. Wait until you receive an email that your request has been approved.
  • In the ''Projects'' tab click the Create New Project button
  • Fill in the form as shown in the picture on the left; Use your own initials and complete the expiration field
  • Press the Create Project button
  • Congratulations you have created a project

    3. Invite people to join your project

    When you create a new project for your class, you would want to add the TA and the students in your class.

    Create a GENI Project
    1. Choose one person from the room to be your TA and one to be your student and write down their email addresses.
    2. From the Project page press the button Invite New Project Members
    3. Fill in the form using both email addresses and press the Invite button
    4. Check your email, you might have an invitation from another user
    5. Follow the instructions about joining their project.
    6. Check your email for the request that someone joined your project and follow the instructions to add them to your project. Add your TA as an Admin and your student as a Member. This way the TA can Invite more people and/or approve join requests.

    Congratulations, you added your collaborators to your project!

    4. Join an existing project


    1. Go to the Projects Tab
    2. Press the Join the Project button
    3. Color(#FFFFFF, #FF0000, From the list of projects find the one named 'tutorial' and press '''Join''')?

    5. Create an experiment

    Now that your project is all setup, you are ready to run your first GENI experiment. For the purpose of this tutorial we are going to use a sample assignment that compares a UDP based transfer protocol with a TCP one.

    Create a GENI Project
    1. Go to the Home tab.
    2. In the project that '''you''' created press the Create Slice button
    3. As a slice name use udt, you can leave the description empty and press Create Slice
    4. Select Add Resources
    5. Since this if the first time you are trying to reserve resources, you should see a warning on the top about not having an SSH key in your account. Access to compute resources in GENI is provide through ssh key pairs and thus the portal needs a public key to upload to compute resources. For the purposes of the tutorial we will have the portal creating an SSH key pair for you. However, if you prefer to use your personal public key you can choose to upload it. Click on the Generate and Download SSH Keypair button.
    6. Press the Download Private Key button
    7. Open a terminal and execute ssh-add ~/Downloads/id_geni_ssh_rsa
    8. Go to the Slices tab and press again on the Add Resources button. This time there should be no warning. Complete the form as as shown in the picture on the left and press the Reserve Resources button
    9. While we wait for our resources to get ready, lets look at another tool that is integrated with the portal. Go to the Slices tab and press the Launch Flack button.

    6. Run your experiment

    Once your resources are ready, your slice in Flack will be green. Once this is done we can now continue to the interesting part of running through the sample assignment. For this we will need to know how to transfer files with UDT, with FTP and how to change the link parameters between the link that connects the two hosts. Follow these instructions that will guide you through doing this with your nodes:

    6a. File Transfer Using UDT

    Follow these steps to perform a file transfer using UDT.

    • Log into pc1 and pc2 in separate windows.
    • On pc1, start a UDT file transfer server, using this command:
      % pc1:~% /local/udt4/app/sendfile
      server is ready at port: 9000
    • On pc2, start a UDT file transfer client, using this command:
      pc2:~% /local/udt4/app/recvfile pc1 9000 /local/datafiles/sm.10M /dev/null

    You should see output like the following in your pc1 window, showing the results of the file transfer. Note the transfer rate.

    new connection:
    speed = 7.14472Mbits/sec
    • There are three data files available for transfer tests: /local/datafiles/sm.10M is 10MB, /local/datafiles/med.100M is 100MB, and /local/datafiles/lg.1G is 1000MB. Leave your transfer server running on pc1, and try transferring each of these files in turn by typing the appropriate commands on pc2. Keep track of the transfer rates in each case.
    • You can leave your UDT server running or stop it with ctrl-C.

    6b. File Transfer Using FTP

    Follow these steps to perform a file transfer using FTP.

    • For a TCP-based (FTP) transfer, there's already a FTP server running on pc1. Log into pc2, and start an ftp client:

    (You type ftp pc1, the user name anonymous, and any password you want, although your e-mail address is traditional.)

    pc2:~% ftp pc1
    Connected to PC1-lan1.
    220 (vsFTPd 2.3.2)
    Name (pc1:mberman): anonymous
    331 Please specify the password.
    230 Login successful.
    Remote system type is UNIX.
    Using binary mode to transfer files.
    • Still on pc2, request a file transfer. Note the reported file size, transfer time, and transfer rate.
    ftp> get med.100M /dev/null
    local: /dev/null remote: med.100M
    200 PORT command successful. Consider using PASV.
    150 Opening BINARY mode data connection for med.100M (104857600 bytes).
    226 Transfer complete.
    104857600 bytes received in 8.91 secs (11491.9 kB/s)
    • You can perform additional transfers with additional get commands. When you're done, exit the ftp client with the quit command.

    6c. Viewing and Adjusting link characteristics

    In this experiment, you'll be changing the characteristics of the link and measuring how they affect UDT and TCP performance.

    • Log into your delay node as you do with any other node. Then, on your delay node, use this command:
      %sudo ipfw pipe show

    You'll get something like this:

    60111: 100.000 Mbit/s    1 ms   50 sl. 1 queues (1 buckets) droptail
        mask: 0x00 0x00000000/0x0000 -> 0x00000000/0x0000
    BKT Prot ___Source IP/port____ ____Dest. IP/port____ Tot_pkt/bytes Pkt/Byte Drp
      0 ip        7     1060  0    0   0
    60121: 100.000 Mbit/s    1 ms   50 sl. 1 queues (1 buckets) droptail
        mask: 0x00 0x00000000/0x0000 -> 0x00000000/0x0000
    BKT Prot ___Source IP/port____ ____Dest. IP/port____ Tot_pkt/bytes Pkt/Byte Drp
      0 ip        8     1138  0    0   0

    This information shows the internal configuration of the "pipes" used to emulate network characteristics. (Your output may look different, depending on the version of ipfw installed on your delay node. In any case, the information you need is on the first line of output for each pipe.)

    You'll want to make note of the two pipe numbers, one for each direction of traffic along your link. In the example above, they are 60111 and 60121.

    There are three link characteristics we'll manipulate in this experiment: bandwidth, delay, and packet loss rate. You'll find their values listed in the ipfw output above. The link bandwidth appears on the first line immediately after the pipe number. It's 100Mbps in the example shown above. The next value shown is the delay, 1 ms in the example above. The packet loss rate (PLR) is omitted if it's zero, as shown above. If non-zero, you'll see something like plr 0.000100 immediately after the "50 sl." on the first output line.

    It is possible to adjust the parameters of the two directions of your link separately, to emulate asymmetric links. In this experiment, however, we are looking at symmetric links, so we'll always change the settings on both pipes together.

    Here are the command sequences you'll need to change your link parameters. In each case, you'll need to provide the correct pipe numbers, if they're different from the example.

    • To change bandwidth (100M means 100Mbits/s):
      sudo ipfw pipe 60111 config bw 100M
      sudo ipfw pipe 60121 config bw 100M
    • Request a bandwidth of zero to use the full capacity of the link (unlimited):
      sudo ipfw pipe 60111 config bw 0
      sudo ipfw pipe 60121 config bw 0
    • To change link delay (delays are measured in ms):
      sudo ipfw pipe 60111 config delay 10
      sudo ipfw pipe 60121 config delay 10
    • To change packet loss rate (rate is a probability, so 0.001 means 0.1% packet loss):
      sudo ipfw pipe 60111 config plr .0001
      sudo ipfw pipe 60121 config plr .0001
    • You can combine settings for bandwidth, delay, and loss by specifying more than one in a single ipfw command. We'll use this form in the procedure below.

    Experiment Procedure

    • Set your link parameters to use maximum bandwidth, no delay, no packet loss:
    sudo ipfw pipe 60111 config bw 0 delay 0 plr 0
    sudo ipfw pipe 60121 config bw 0 delay 0 plr 0
    • Verify with
    sudo ipfw pipe show
    60111: unlimited    0 ms   50 sl. 1 queues (1 buckets) droptail
        mask: 0x00 0x00000000/0x0000 -> 0x00000000/0x0000
    BKT Prot ___Source IP/port____ ____Dest. IP/port____ Tot_pkt/bytes Pkt/Byte Drp
      0 ip        7     1060  0    0   0
    60121: unlimited    0 ms   50 sl. 1 queues (1 buckets) droptail
        mask: 0x00 0x00000000/0x0000 -> 0x00000000/0x0000
    BKT Prot ___Source IP/port____ ____Dest. IP/port____ Tot_pkt/bytes Pkt/Byte Drp
      0 ip        8     1138  0    0   0

    Note that bandwidth is set to unlimited, delay to 0 ms, and no PLR is shown.

    • Using this initial setting, try a few UDT transfers, including the larger files. Now try FTP transfers. Record the transfer sizes and rates.
    • Now change the link parameters to reduce the available bandwidth to 10Mbps:
    sudo ipfw pipe 60111 config bw 10M delay 0 plr 0
    sudo ipfw pipe 60121 config bw 10M delay 0 plr 0
    • Repeat your file transfers with the new settings. As before, note the transfer sizes and rates, as well as the link settings.
    • Continue with additional trials, varying each of the three link parameters over a range sufficient to observe meaningful performance differences. Record your data.

    7. Delete your experiment

    When we are done with our experiment it is always good to clean up and release our resources so other people can use them.

    1. Go back to the portal and press on the Slices tab
    2. In your slice press the Release Resources button

    Congratulations you have successfully completed your first GENI assignment!