Hive Machine Setup

This page contains instructions for connecting to the hive machines, which may be useful for Project 1.

SSH Information

There’s nothing for you to do in this section, but please read through it so you understand what we’re about to do.

Project 1 can be run on the hive machines, a set of 30 computers in Soda Hall on campus. You could work on the project using the computers on campus. However, to support running the project off-campus, we’re going to use SSH, which lets you connect to the hive machines remotely. With SSH, you can enter commands on your own computer that will be run on the hive machines, and see the outputs from the hive machine on your own computer.

To get an account on the hive machines, you will create an account on the EECS website. This will give you a username and password, which you could use to log in physically on the hive computers.

To SSH onto the hive machines using your username and password, you would run a command like ssh username@hive1.cs.berkeley.edu. Here, username is specific to your account, and hive1.cs.berkeley.edu is the Internet address of the hive computer (so everyone connecting to this machine uses this address).

Since this SSH command is long, we’ll add a line in your SSH configuration file that lets you write something like ssh hive1 as a shorthand for the longer command above.

The SSH command will prompt you for a password every time you log in. To avoid having to type your password every time, we will set up key-based authentication. You’ll create a key on your local computer. Then, you’ll copy this key over to the hive machines. In the future, instead of asking you for a password, the SSH process will automatically use the keys on your computer and the hive computer to authenticate you.

One last thing we need to consider is Berkeley’s network policy, which by default disallows SSH connections from non-Berkeley networks. During setup, you will need to join a Berkeley network. In the SSH configuration file, we will add a line to allow connections from non-Berkeley networks. After you’ve finished setup, you should be able to SSH from any network.

Note that Project 1 on the hive machines runs on a virtual machine (VM), which is an operating system running on the hive. Once you’re on the hive machines, you’ll need to SSH from the hive machines into the VM. This means that you’ll actually be running two layers of SSH: one layer from your local computer to the hive machine, then another layer from the hive machine into the project VM.

Creating an Instructional Account

  1. Visit the EECS web account page.
  2. Click “Login using your Berkeley CalNet ID”.
  3. Find the cs161 row, and click “Get a new account”.
  4. Write down the account login (cs161-xxx, where xxx is 3 letters unique to you), and the password. You will need them later.

Connect to a Berkeley Network

There are two ways you can connect to the Berkeley network:

Option 1: Connect to eduroam, the Wi-Fi network on campus. You need to physically be on campus for this option.

See https://technology.berkeley.edu/wi-fi if you need help connecting to eduroam.

Option 2: Install the Berkeley VPN. If you are not physically on campus, you need to choose this option.

  1. Download and install the VPN software. Windows and Mac users: https://vpn.berkeley.edu/global-protect/getsoftwarepage.esp

    Alternate, open-source version for Linux users: https://github.com/yuezk/GlobalProtect-openconnect

  2. Open the newly installed “GlobalProtect” app and enter vpn.berkeley.edu as the portal address. You will be prompted to log into CalNet, and then you will be connected to the VPN.

successfully connected vpn page

SSH Key Setup

All steps in this section should be performed on your local computer. For this section, do not SSH into any remote machine.

All steps in this section should be performed while connected to the Berkeley network (either on eduroam, or with the VPN connected).

  1. Open a terminal. Don’t use a terminal built into a text editor like VSCode. On Windows machines, we recommend Git Bash.

  2. Run the following command in your terminal: 
    curl -s https://assets.cs161.org/proj1/get-ssh-key.sh | bash

    If it worked, you should see “Success!” displayed in the terminal.

  3. Run the following command in your terminal: 
    ssh-copy-id cs161-xxx@hive5.cs.berkeley.edu

    If you’re getting “Connection refused” or “Connection timeout” or other connection errors, try using a different hive between hive1 and hive30 (e.g. replace hive5 with hive6).

    If you see a prompt like “Are you sure you want to continue connecting”, you can type yes.

    If it worked, you should see a password prompt, like cs161-xxx@hive5.cs.berkeley.edu's password:

  4. In the password prompt, type in the account password you obtained when you created an instructional account. You will not see the password appear in the terminal as you type it; this is intended.

    If it worked, you should see “Number of key(s) added: 1” (the number should not be zero).

SSH Configuration Setup

All steps in this section should be performed on your local computer. For this section, do not SSH into any remote machine.

All steps in this section should be performed while connected to the Berkeley network (either on eduroam, or with the VPN connected).

  1. Create a ~/.ssh folder by running this command in your local terminal:

    mkdir -p ~/.ssh

  2. Open ~/.ssh/config in Vim (terminal-based text editor) by running this command in your local terminal:

    vim ~/.ssh/config

  3. In Vim, press the i key to enter insert mode. -- INSERT -- should appear at the bottom left.

  4. Remove any SSH configurations from previous Berkeley CS classes.

    These lines are from CS 61B. If you don’t need them anymore, use the arrow keys and backspace to delete them.

    Host *.cs.berkeley.edu *.eecs.berkeley.edu
IdentityFile ~/.ssh/cs61b_id_rsa

    These lines are from CS 61C. If you don’t need them anymore, use the arrow keys and backspace to delete them.

    # Begin CS61C hive machine config
...
# End CS61C hive machine config

    If you need configuration for CS 61C and CS 161 simultaneously, you should keep only CS 61C’s config (don’t add CS 161’s config). When SSHing, you’ll need to explicitly type the usernames: ssh cs61c-xxx@hive22 or ssh cs161-xxx@hive22.

    If there are config lines from another class that you still need, reach out to CS161 course staff.

  5. Copy the following text into the file: 
    # Begin CS161 hive machine config
Host hive? hive??
    HostName %h.cs.berkeley.edu
    ProxyJump cs161-xxx@instgw.eecs.berkeley.edu
Match Host *.cs.berkeley.edu
    Port 22
    User cs161-xxx
    ServerAliveInterval 60
# End CS161 hive machine config

    Replace both instances of xxx with the three-letter account login you obtained when you created an instructional account.

  6. Exit insert mode by pressing Esc. -- INSERT -- should be gone.
  7. Save the file by typing :w, then Enter.
  8. Quit Vim by typing :q, then Enter.

Connecting to the Hive

All of the above setup steps should only need to be done once, at the start of the semester.

After finishing the setup steps, to connect to the hive machines, you should only need to run the following command in your local machine terminal, replacing X with a number between 1 and 30:

ssh hiveX

If you see a prompt like “Are you sure you want to continue connecting”, you can type yes.

This command should start an SSH session, even if you’re not connected to a Berkeley network (e.g. not on eduroam and not connected to the VPN).

If it worked, you should see some output scroll by, followed by a terminal prompt:

hive6 [1] ~ #

At this point, any commands you type into this terminal will be executed by the remote hive machine on campus.

To log out of the SSH session and return to your local computer terminal, type exit.

Troubleshooting:

  • If you’re getting “Connection refused” or “Connection timeout” or other connection errors, try using a different hive between hive1 and hive30 (e.g. run ssh hive7 instead). Note: the Hivemind website used to be used to check which hive machines are busy or offline. It is now broken, please do not refer to it anymore.
  • If you’re getting “Connection timeout” or other connection errors, make sure you’re not on the Berkeley-Visitor Wi-Fi network, which blocks SSH connections. If you’re on Berkeley-Visitor, switch to eduroam or turn on the Berkeley VPN.
  • If your ssh setup script is not working (for example you are getting a “Permission Denied” error), you can still access the hives by using the command ssh cs161-XXX@hiveY.cs.berkeley.edu, replacing XXX and Y, and using your instructional account password.