Creating the First Project

We are working on better automating many of the procedures in this chapter. For now, though, a few of them are still manual. Steps labeled "Local Only" are only required when setting up a testbed with local nodes - they can be skipped in a widearea-only testbed.

Step 1 - Setup users, projects, and experiments

Before proceeding, ensure that you have the following working (from the boss and ops setup documentation):

• NFS mounts between boss and ops
• Root SSH keys (so that root on boss can ssh to ops without a password)
• The web interface

Make sure you can log into the web interface using the 'elabman' account. The password for the elabman account is the same as the root password on your boss node (see, we told you to remember it!).

This account is created as a testbed administrator, but there is one thing you will need to do in order to use your admin powers. For the same reason you use 'su' and/or 'sudo' on your UNIX boxes instead of logging in as root, you must explicitly enable admin privileges on Emulab after you log in. When logged in as a user who is allowed to become and admin, you will see a green dot on the center of the top header above the main page content. The green dot means that although you are allowed admin powers, they are currently turned off, and you see the same web pages that a regular user sees, and can use the same actions. If you click on the dot, it will turn red, and you will have full administrator privileges. We call this 'going red dot'. If you click on the dot again, it will go back to green, thus you can easily flip back and forth between normal privileges and admin privileges. Note that most of the procedures in this chapter require you to be in red dot mode.

Now, we will use the elabman user to bootstrap your first real account and project. Note that while you will use the elabman account to do this, the elabman account should not be considered a real account; it is intended to help bootstrap only, and as such, does not have the power to perform many actions that are required later, such as adding new nodes to the testbed.

Login as user 'elabman' if you have not already done so. Go into 'red dot mode' by clicking on the green dot on the top of the page. You should see the 'Start a New Testbed Project" page, with a "Create First Project" link on the menu under "Experimentation".

Fill in your own information in the 'Project Head Information' section. It is important that you provide a working email address! Select your initial Project Name in the 'Project Information' section (we call ours 'testbed', but you can call yours whatever you call your project or research group). Also, specify a working URL (it is required) for the project. Submit this form using the Submit button at the bottom of the page. The web interface will grind along for a minute or so. Do not click the stop button! When it is all done, you will see a message that invites you to login as the user you just created. Do this now so that you can continue with setting up your testbed. Note that the elabman account was deactivated during this process to avoid problems later on (and potential security breaches).

Before we continue, let's explain a few more important items:

• Project Membership: In addition to the project you just created, you have automatically been added to the "emulab-ops" project with trust value "group_root". This allows you to approve new members to that project as well as your own project.
• Admin Mode: Your new account has been given "administrator" mode, as described above. To change that value for other users after their accounts have been created, you can do this on boss:

  echo 'update users set admin=1 where uid="<username>"' | mysql tbdb
          

• Shell on Boss: Give yourself the special ability to login to boss. In contrast, most (normal) users have a restricted shell on boss, and are not allowed to log in using a password. Login to boss as root, and edit the password file using the 'vipw' command (FreeBSD requires some special processing on the password file after editing, which vipw does). Give yourself a real shell (say, /bin/csh) and then exit the editor. Then give yourself a password (in general, it is safer to have a different password on boss than on ops!). Use this command:

  passwd <your username>

  Note:

  See the file 'shellonboss.txt' in the testbed source doc tree for important security issues concerning giving real shells on boss. Before you give a real shell to someone, it is a good idea for them to read this file!

• Now logout and log back in as yourself. In general, it is safer and better to not do things as root. In fact, many testbed programs will complain if you invoke them as root because it makes accounting and auditing more difficult.
• Unix Group Membership: The Emulab account system manages both the password file and the group file (/etc/group) on both boss and ops. If you edit them directly, those changes will likely be lost. If you want to be a member of any UNIX groups on boss, use our 'unixgroups' command. For example, to add yourself to the "operator" group, you would run the following on boss (as yourself, not root):

  withadminprivs unixgroups -a <username> operator

  Note that your initial account created previously was already placed in the wheel and tbadmin groups.

  Note:

  Just as you need to go 'red dot' to use admin privileges on the web interface, you must also explicitly enable them on the command line. To do this prefix the command you want to run with 'withadminprivs', which can be abbreviated as 'wap'.

• Set Your Path: withadminprivs and many other admin-type commands live in /usr/testbed/sbin - you'll want to put this and /usr/testbed/bin in your $PATH environment variable.

Others at your site can now apply to join your project, or start their own.

Step "-1" - Undoing Step 1 if necessary

If something went wrong during Step 1, it can leave things in an inconsistent state. Here's how to undo it without starting over from scratch. The goal is to remove things that boss-install checks on, so it can be run again to put the Emulab database and directories into initial conditions.

• Remove users, groups, and directories set up by boss-install.

  pw userdel -n elabman -r
  pw userdel -n elabckup -r
  ssh -n ops pw userdel -n elabman -r
  ssh -n ops pw userdel -n elabckup -r
  
  ls -l /users /proj /groups
  rm -r /proj/* /groups/*
  mkdir /proj/cvsrepos
  pw groupdel -n emulab-ops
  ls -l /usr/testbed/{expwork,*/proj}
  rm -r /usr/testbed/expwork/* /usr/testbed/*/proj/*
  ls -l /usr/testbed/{expwork,*/proj}

• Remove user and group from the elabman "Create First Project" pages.

  set me = *your-login*
  set us = testbed
  pw userdel -n $me -r
  pw groupdel -n $us
  ls -l /users /proj /groups

• Also remove any other users and groups you've created since then. Otherwise you will get this message until you've cleared them:

  Error Creating Project: Transient error; please try again later.

  Run the following to remove any other users and groups:

  tail /etc/passwd
  tail /etc/group
  set him = *user*
  set them = *group*
  pw userdel -n $him -r
  pw groupdel -n $them