NOTICE

This HOWTO is for version 19 of the CS50 Appliance.

  • If taking CS50x, CSCI E-50, or CS50’s certificate option, you should use this version of the appliance.

  • If following Fall 2013 of CS50 (or CSCI E-50), you should use this version of the appliance.

  • If following Fall 2012 of CS50 (or CSCI E-52), you should use version 17 of the appliance.

  • If following Summer 2012 of CSCI S-75, you should also use this version of the appliance.

  • If following Spring 2012 of CS1, CS51, or CS164, you should use version 3 of the appliance.

  • If following Fall 2011 of CS50, you should use version 2.3 of the appliance.

  • If following Fall 2010 of CS50, you should use version 2.1 of the appliance.

  • If following Fall 2009 of CS50, you should use version 1.4 instead.

The CS50 Appliance is a virtual machine (VM) that lets you "take" CS50 (and other courses!), even if you’re not a student at Harvard.

It’s based on Fedora, a Linux-based operating system. It’s an appliance in the sense that we’ve preconfigured this VM for a specific purpose: CS50!

In other words, even if you’re not a student in CS50, you can still play along at home. The CS50 Appliance will let you compile source code from lectures and implement problem sets without having to figure out how to configure clang, etc. yourself. Moreover, the CS50 Appliance lets you run Linux inside of a window on your own computer, even if you’re already running (some other version of) Linux, Mac OS, Solaris, or Windows!

Incidentally, the appliance is always work in progress, so please forgive any bugs!

Cheatsheet

See instructions for much more detail.

Your Name

John Harvard

Your Username

jharvard

Your Password

crimson

Appliance’s IP Address

a number of the form w.x.y.z, which can be found in the appliance’s bottom-right corner

Appliance’s Version

a number of the form 19-#, which can be found in the appliance’s bottom-right corner

Your MySQL Username

jharvard

Your MySQL Password

crimson

phpMyAdmin

http://localhost/phpMyAdmin/ from within the appliance

http://w.x.y.z/phpMyAdmin/ from your own computer

In version 19 of the appliance, the superuser account (i.e., root) is locked (i.e., disabled). But John Harvard has "sudo" (i.e., administrative) privileges.

Notice

For research purposes, the CS50 Appliance is designed to log:

  • command-line commands (e.g., ls, make hello, etc.);

  • the output of programs like clang, check50, gdb, style50, etc.;

  • gdb commands; and

  • source code that you create and/or save inside of the appliance. Those logs are then periodically uploaded to CS50’s servers.

Among CS50’s overarching research goals are to understand better how students code, how students respond to error messages, and how students progress from non-working to working code. None of the data that’s logged is used to compute grades.

The CS50 Appliance does not (and cannot) log any activities or files on your own Mac or PC (outside of the CS50 Appliance). It can only log activity inside of the CS50 Appliance (i.e., inside of its own window). Even so, you may disable the uploading of logs to CS50’s servers if you would like to opt out of this research. Simply run no50 in a terminal window to opt out.

Instructions

How to Install Appliance

In order to install the CS50 Appliance, you first need to install a hypervisor, which is a program that will let you run virtual machines on your own computer, whether you run Mac OS, Windows, or Linux.

Alternatively (and particularly if you run into trouble with VMware Fusion or VMware Player), you can follow these instructions for VirtualBox.

Once installed, it’s not uncommon for the appliance to take a minute or so to boot. But if, once at John Harvard’s desktop, the appliance still feels unbearably slow, you might need to enable hardware virtualization on your computer if it’s a PC running Windows or Linux. (Hardware virtualization should be enabled by default on any Intel-based Mac manufactured in the past few years.) Even with hardware virtualization enabled, though, virtual machines might still feel slow if your computer is a few years old, has a CPU that’s only 1GHz or so, or has only 1GB or so of RAM.

How to Update Appliance

To determine which version of the appliance you have, simply look in the appliance’s bottom-right corner, where you should see 19- in boldface, where is a number. Alternatively, you can open a terminal and execute

appliance50 -v

which should report 19-# as well.

To ensure you have the latest version of the appliance, you can update yourse by opening a terminal and executing:

update50

An update may take several minutes.

Note that you cannot update from version 1.4, 2.1, 2.3, 3, 17a, or 17 of the appliance to version 19. You must instead download 19, per the instructions above.

How to Use Appliance

The first thing you should see when the appliance boots up is John Harvard’s desktop. (Oh, henceforth, you are John Harvard. Your initial password is crimson. And here’s what you look like.) Even though you might think of Linux as having only a command-line interface, graphical user interfaces do exist. We’ve installed Xfce, one of the most popular, for you. However, we installed as few programs as possible to keep the appliance small. You’re welcome to install additional programs via Menu > Administration > Software.

How to Change Name

As much as you might not like being called John, do not try to change John Harvard’s name or username. Life will be simpler as John.

With that said, if you’d really like to be yourself (or someone else altogether), you’re welcome to create a new account. Open a terminal and execute

sudo adduser --comment "Jane Harvard" --gid students --groups wheel janeh
echo crimson | sudo passwd --stdin janeh
echo -e "crimson\ncrimson" | sudo smbpasswd -a -s janeh

where Jane Harvard is your desired name, crimson is your desired password, and janeh is your desired username. Be sure not to overlook the \n in the second command.

If you’d also like to start logging into the appliance automatically under your new identity (instead of John Harvard’s), execute

sudo nano /etc/gdm/custom.conf

and change jharvard to your own username. Then hit ctrl-x, then y, then Enter to save and quit.

How to Change Password

You can change your password in any of these ways:

  • Select Menu > Settings > Password and follow the on-screen prompts.

  • Open a terminal and execute:

    passwd

With that said, allow us to suggest that you not change John Harvard’s password if your own computer is already password-protected. (Life will be simpler with crimson.) The appliance has been configured in such a way that only someone with access to your computer (e.g., you) can access the appliance. Even though the appliance can connect to the Internet, the Internet cannot connect to the appliance.

How to Change Language

This feature may require Internet access.

If English is not your native language, you may want to change the appliance’s default language. Some things will remain in English, but you might find yourself more at home nonetheless. Select Menu > Administration > Language, inputting your password if prompted. Select your preferred language from the list that appears, then click OK. If prompted, click Import key. You may need to wait for a bit as the language is installed. Then restart the appliance and log back in.

How to Change Keyboard Layout

If you have a non-U.S. (or non-standard) keyboard, you may want (or need!) to change your keyboard’s layout as follows.

  1. Select Menu > Settings > Keyboard.

  2. Click Layout.

  3. Uncheck Use system defaults.

  4. Leave Keyboard model blank unless you have one of the keyboards listed.

  5. Click Add down below Keyboard layout.

  6. Select your keyboard’s layout (and variant, if any).

  7. Click OK.

  8. Ensure that your selection is now highlighted instead of English (US), then click Close.

How to Change Time Zone

If you don’t live in Cambridge, Massachusetts, USA, you may want to change the appliance’s timezone. Select Menu > Administration > Date & Time. Click the Time Zone tab, select the nearest city in your time zone, then click OK, leaving System clock uses UTC checked.

How to Open a Terminal

You can open a terminal in any of these ways:

  • Select Menu > Programming > Terminal or Menu > Accessories > Terminal. You’ll find yourself in your home directory (~).

  • Click Terminal’s icon (a black square) in the appliance’s bottom-left corner. You’ll find yourself in your home directory (~).

  • Right-click anywhere on your desktop and select Open Terminal Here. You’ll find yourself in ~/Desktop/.

  • Select Menu > Programming > gedit or Menu > Accessories > gedit. You’ll find yourself in your home directory (~) in gedit’s bottom panel.

No matter the approach you take, it’s in the terminal window that you’ll be able to type commands like cd, gcc, ls, etc.

How to SSH to Appliance

If you’d like to SSH to the appliance from your own computer (as with Terminal on Mac OS or with PuTTY on Windows), you can SSH from your computer to the appliance’s IP address (which is displayed in the appliance’s bottom-right corner).

Note that, for security’s sake, you can SSH to the appliance as jharvard but not as root.

How to Assign Appliance a Static IP Address

Coming Soon

How to Change Resolution

You can change the appliance’s resolution (i.e., width and height) in either of these ways:

  • Select Menu > Settings > Display within the appliance, select a new value to the right of Resolution, then click Close.

  • Click and drag the appliance’s bottom-right corner.

How to Change Volume

  1. Select Menu > Sound & Video > Mixer.

  2. Select Playback: ES1371 [AudioPCO-97] Analog Stereo (PulseAudio Mixer) next to Sound card.

  3. Click '''Select Controls…".

  4. Check Master then click Close.

  5. Drag the sliders upward to increase the audio’s volume.

  6. Click Quit.

  7. Visit http://www.youtube.com/ in Chrome to test with a video!

How to Enter/Exit Fullscreen Mode

To enter fullscreen mode, select Switch to Fullscreen from VirtualBox’s Machine menu while the appliance is running. (This menu is outside of the appliance, not inside of it.)

To exit fullscreen mode, move your cursor to the middle of the bottom of your screen, at which point a menu should appear. Click the second icon from the right (which resembles two squares).

How to Use phpMyAdmin

You can access phpMyAdmin in either of these ways:

No matter the approach you take, log in as jharvard with a password of crimson if prompted.

How to Restore Snapshots

Every 10 minutes, the appliance take "snapshots" of source code in /home just in case you accidentally delete something. You can also mitigate accidental deletions by synchronizing with Dropbox so that you can restore files at dropbox.com.

Suppose that you just deleted ~/hello.c. Odds are you’ll find it in the minutely.0 or minutely.1 snapshot, depending on the current time, in which case you can recover it with

cp /.snapshots/minutely.0/home/jharvard/hello.c ~

or with

cp /.snapshots/minutely.1/home/jharvard/hello.c ~

in a terminal. If you need to recover an earlier version, you can go further back in time via minutely.2, minutely.3, or minutely.4. If you’d instead like to go back an hour or so, you can start with hourly.0, followed by hourly.1, hourly.2, and so on. Below are all of the intervals you can try. Realize that the times only estimates, since the intervals' definitions depend on the current time.

minutely.0

10 minutes ago

minutely.1

20 minutes ago

minutely.2

30 minutes ago

minutely.3

40 minutes ago

minutely.4

50 minutes ago

hourly.0

1 hour ago

hourly.1

2 hours ago

hourly.22

23 hours ago

daily.0

yesterday

daily.1

2 days ago

daily.5

6 days ago

weekly.0

1 week ago

weekly.1

2 weeks ago

weekly.51

51 weeks ago

To see which intervals are actually available to you, execute:

ls /.snapshots/

How to Enable Dropbox

This feature requires Internet access.

To make it easier to back up files within the appliance automatically as well as share them with your own computer(s), you can synchronize a directory in John Harvard’s account with Dropbox. If taking a course, just take care to respect the course’s policies on academic honesty.

Here’s how to configure the appliance for Dropbox.

  1. Select Menu > Dropbox.

  2. You should be prompted to "download the proprietary daemon" (i.e., software); click OK. The software should proceed to download and unpack.

  3. You should then be prompted to set up Dropbox.

    • If you don’t already have a Dropbox account, leave I don’t have a Dropbox account checked, then click Next. Create your Dropbox as prompted.

    • If you already have an Dropbox account, check I already have a Dropbox account, then click OK. Log in as prompted.

  4. If prompted to upgrade your Dropbox, simply leave 2 GB checked (which is free) then click Next, unless you want to upgrade to a paid account.

  5. If prompted to Choose setup type, leave Typical checked, then click Install. If prompted to "merge", click Merge.

  6. If prompted to take a 5-step tour, click Skip Tour; its screenshots won’t match what you’ll see in the appliance.

  7. When informed That’s it!, uncheck Open my Dropbox folder now, then click Finish. A Dropbox icon should then appear in the appliance’s bottom-right corner.

Only those files and folders that you save in ~/Dropbox/ will be synchronized with your Dropbox account.

How to Prevent Dropbox from Synching Personal Files into the Appliance
  1. Ctrl-click on the Dropbox icon in the appliance’s bottom-right corner and select Preferences….

  2. Click Advanced.

  3. Click Selective Sync….

  4. Uncheck the folders that you don’t want synched into the appliance.

  5. Click Update.

How to Transfer Files between Appliance and Your Computer

If you’d like to SFTP to the appliance from your own computer (as with Cyberduck on Mac OS or with WinSCP on Windows), you can SFTP from your computer to w.x.y.z (where w.x.y.z is the appliance’s IP address, which can be found in the appliance’s bottom-right corner).

Alternatively, you can "mount" John Harvard’s home directory (via a protocol called SMB, otherwise known as CIFS) in a window on your own desktop, to and from which you can drag and drop files. Here’s how, whether you run Linux, Mac OS, or Windows.

Windows
  1. Open any folder on your hard drive.

  2. Click the address bar atop the folder’s window and input \\w.x.y.z\jharvard (where w.x.y.z is the appliance’s IP address, which can be found in the appliance’s bottom-right corner), then click Enter.

  3. If prompted for your name and password:

    1. Input jharvard for User name.

    2. Input crimson for Password.

    3. Check Remember my credentials if you’d like.

    4. Click Connect.

John Harvard’s home directory should then open in a new window.

Mac OS
  1. Select Connect to Server… from the Finder’s Go menu.

  2. Under Server Address:, input smb://w.x.y.z (where w.x.y.z is the appliance’s IP address, which can be found in the appliance’s bottom-right corner). (Click the + icon if you’d like to add the appliance to your Favorite Servers.) Then click Connect.

  3. If prompted for your name and password:

    1. Select Registered User.

    2. Input jharvard for Name.

    3. Input crimson for Password.

    4. Click Connect.

John Harvard’s home directory should then open in a new window.

Linux

GNOME

  1. Select Connect to Server… from the Places menu.

  2. Input w.x.y.z for Server (where w.x.y.z is the appliance’s IP address, which can be found in the appliance’s bottom-right corner).

  3. Select Windows share for Type.

  4. Input jharvard for Share.

  5. Input / for Folder.

  6. Input CS50 for Domain name.

  7. Input jharvard for User name.

  8. Input crimson for Password.

  9. Check Remember this password if you’d like.

  10. Click Connect.

John Harvard’s home directory should then open in a new window.

KDE

  1. Open Dolphin (as via Computer > Network).

  2. Select Network.

  3. Click Add Network Folder.

  4. Select Microsoft® Windows® network drive, then click Next.

  5. Input appliance for Name.

  6. Input w.x.y.z for Server (where w.x.y.z is the appliance’s IP address, which can be found in the appliance’s bottom-right corner).

  7. Input jharvard for Folder.

  8. Check Create an icon for this remote folder if you’d like.

  9. Click Finish.

  10. Input jharvard for Username.

  11. Input crimson for Password.

  12. Check Remember password if you’d like.

  13. Click OK.

John Harvard’s home directory should then open in a new window.

Xfce

  1. Install gvfs-smb as root (as via sudo) if not installed already, as with

    yum -y install gvfs-smb

    if running CentOS, Fedora, or RedHat or with

    apt-get install gvfs-backends

    if running Debian or Ubuntu.

  2. Launch Thunar (as via Applications Menu > System > Thunar File Manager).

  3. Select Open Location… from the Go menu.

  4. Input smb://w.x.y.z/jharvard/ (where w.x.y.z is the appliance’s IP address, which can be found in the appliance’s bottom-right corner) for Location then click Open.

  5. Input jharvard for Username.

  6. Input CS50 for Domain.

  7. Input crimson for Password.

  8. Check Remember forever if you’d like.

  9. Click Connect.

How to Access Appliance from Another Computer

This feature is not supported on Harvard’s campus on the "Harvard University" SSID. It does work on the "CS50" SSID in Annenberg and Sanders Theatre, though.

By default, you can access the appliance from your own computer via w.x.y.z (where w.x.y.z is the appliance’s IP address, which can be found in the appliance’s bottom-right corner). That IP address only exists within the confines of your hypervisor, though, so, by default, it’s not possible to access the appliance from other computers on your LAN (i.e., home network).

However, the appliance also comes with a "bridged" network interface (eth2) that you can activate manually. So long as your LAN supports DHCP (which most home networks do), that interface will acquire an IP address on your LAN, at which point you can access the appliance via HTTP or SSH via that IP from any computer on your LAN.

However, for security’s sake, you will not be able (from any computer besides your own, on which the appliance is running) to:

You will be able to:

  • access John Harvard’s homepage

  • SSH to the appliance

Unfortunately, odds are eth2 will not work on Harvard’s campus because of Harvard’s firewall.

Before activating eth2, you should first change John Harvard’s password to something only you know for security’s sake.

To enable eth2 temporarily, open a terminal and execute:

sudo ifup eth2

If your LAN indeed supports DHCP, you should see:

Determining IP information for eth2... done.

To find out which IP address was assigned by your LAN to the appliance, execute

ifconfig eth2

and look to the right of inet addr (not inet6 addr). That’s the address via which you can accessible the appliance from another computer on your LAN. Odds are it will start with 192.168.0 or 192.168.1 or 10.0.1, though other prefixes are possible.

If you would like to enable eth2 permanently:

  1. Select Menu > Administration > Network.

  2. Highlight eth2 in the window that appears, then click Edit.

  3. Check Activate device when computer starts, then click OK.

  4. Select File > Save, then click OK.

  5. Select File > Quit.

  6. Restart the appliance.

Just realize that each time the appliance starts, it may be assigned a different IP address on your LAN via DCHP, so you might need to re-run

ifconfig eth2

each time to find out the current address. If your home router supports "DHCP reservations," know that you can find out the MAC (i.e., Ethernet) address of eth2 by running

ifconfig eth2

as well. Look to the right of HWaddr for the address. Alternatively, if you think it’s safe to assign the appliance a static IP address on your LAN without your home router even knowing, select Menu > Administration > Network, highlight eth2 in the window that appears, click Edit, select Statically set IP addresses, and configure the interface as you see fit.

How to Take a Screenshot

It’s sometimes helpful to take a screenshot of the appliance so that you can remember or share something you see on your screen. If taking a course, just take care to respect the course’s policies on academic honesty.

To take a screenshot inside of the appliance:

  1. Select Menu > Accessories > Screenshot.

  2. Check a Region to capture.

  3. Leave Capture the mouse pointer checked unless you’d like to hide it.

  4. Leave Delay before capturing at 1, unless you need more time.

  5. Click OK.

  6. You should then be prompted to decide on an Action. Leave Save checked and then click OK if you’d like to save the screenshot as a file; decide on a destination as prompted. You can then share that screenshot with someone if necessary, as by opening Gmail in Firefox and sending it as an attachment.

You can also share control of your screen if you need someone else to see more than a screenshot.

How to Share Control of Your Screen

This feature requires Internet access.

So that you can help (and be helped by!) fellow learners on the Internet, the appliance comes with TeamViewer, which lets you share (control of) your screen with someone else (a "partner") on the Internet (and vice versa). If taking a course, just take care to respect the course’s policies on academic honesty.

To share your screen with some else:

  1. Select Menu > TeamViewer. (Click Accept License Agreement if prompted.) A window should appear.

  2. Tell your partner Your ID and Password that you see. Once your partner inputs those values, your screen should be shared. Though if your own computer has a firewall, you might first be prompted to "allow incoming connections" or the like.

To see someone else’s screen:

  1. Ask your partner for a Partner ID and Password.

  2. Select Menu > TeamViewer. (Click Accept License Agreement if prompted.) A window should appear.

  3. Input the Partner ID into that window, then click Connect to partner.

  4. When prompted, input the Password, at which point you should see your partner’s screen.

If you would like to connect to someone else’s appliance from your own computer (rather than from your own appliance) or from a mobile device, you can download TeamViewer for free for Android, iOS, Linux, Mac OS, or Windows from http://www.teamviewer.com/en/download/.

How to Disable Automatic Login

By default, the appliance logs you in as John Harvard. To disable automatic login, open a terminal and execute:

sudo rm -f /etc/gdm/custom.conf

Then restart the appliance. You should now see a login prompt instead of John Harvard’s desktop.

How to Log Out of Appliance

To log out of the appliance, click Exit.png in the appliance’s bottom-right corner, then click Log Out.

How to Restart Appliance

You can restart the appliance in either of these ways:

  • Click Exit.png in the appliance’s bottom-right corner, then click Restart.

  • Open a terminal and execute the below, inputting your password if prompted:

    reboot

How to Shut Down Appliance

You can shut down the appliance in either of these ways:

  • Click Exit.png in the appliance’s bottom-right corner, then click Shut Down.

  • Open a terminal and execute the below, inputting your password if prompted:

    sudo shutdown

How to Configure Appliance for a Proxy Server

If your own computer sits behind an HTTP proxy server, you might need to configure the appliance to route HTTP traffic through that proxy as well. Here’s how.

  1. Open a terminal and execute the below:

    sudo gedit /etc/profile.d/proxy.sh
  2. Add the following line to that (otherwise empty) file, where example.com is the address of your proxy server and 80 is its port number:

    export http_proxy=http://example.com:80/
  3. Select File > Quit, and click Save when prompted.

  4. Execute

    sudo chmod 644 /etc/profile.d/proxy.sh

    in the terminal.

  5. Restart the appliance.

How to Run Programs from Lectures

How to Do Problem Sets

Accessibility

The CS50 Appliance comes pre-configured with Orca, a screen reader. To enable Orca, select Menu > Accessories > Orca.

Note that Orca does work with:

  • Chrome

  • gedit (but not its built-in terminal window)

  • NetBeans

  • Xfce’s menu (in the appliance’s bottom-left corner)

  • Xfce’s panel (along the bottom of the appliance’s screen)

But Orca does not work with:

  • gedit’s built-in terminal window

  • Terminal

  • Thunar, the appliance’s file manager (via which you can open the Home and File System icons on the appliance’s desktop)

However, if you have a screen reader installed on your own computer, you needn’t rely on Orca alone. Instead, you can leverage your own screen reader for navigation by SSHing to the appliance from your computer and by mounting John Harvard’s home directory on your own computer.

If you have suggestions on how to improve the appliance’s accessibility, please let sysadmins@cs50.net know!

Forget a password?

I changed and forgot John Harvard’s password

  1. Start (or restart) the appliance.

  2. As soon as the appliance starts to boot, click inside of its window (again and again, if need be), until your cursor is "captured" (i.e., disappears).

  3. When you see the black GNU GRUB screen, hit your keyboard’s down arrow to select "Advanced options for Generic', then hit Enter.

  4. On the screen that appears, select (with your keyboard’s arrow keys) the row that’s parenthetically called recovery mode, then hit Enter.

  5. The appliance should boot more quickly than usual. When you see a root@appliance (~): prompt, execute

    passwd jharvard

    and input a new password for John Harvard (e.g., crimson) twice as prompted.

  6. Type

    exit

    to restart the appliance.

You should then be able to log in as John Harvard again.

I forgot John Harvard’s MySQL password

John Harvard’s password for MySQL is crimson by default. But if you changed either to something you do not remember, you can change both back to crimson by opening a terminal and executing the below:

sudo yum -y reinstall appliance50

That command will restore the appliance to "factory defaults." It will not delete any code that you’ve written.

Changelog

Known Issues

None at this time.

Future Work

Below are features that may be included in some future version of the appliance.

  • Add Selenium.

  • Add dnsmasq and resolve *.localdomain to 127.0.0.1.

  • Add support for static IPs.

Acknowledgements

Many thanks to everyone who’s helped us improve the CS50 Appliance, including, but not limited to:

  • Aaron Oehlschlaeger

  • Amir

  • Chris Gerber

  • Dan Armendariz

  • Darrin Ragsdale

  • Dotty

  • Federico Lerner

  • Glenn Holloway

  • James Lankford

  • Kartikeya Srivastava

  • Matthew Polega

  • Matthew Roknich

  • Mauro Braunstein

  • Nobu Kikuchi

  • Philip Durbin

  • R.J. Aquino

  • Rob Bowden

  • Rod Ruggiero

  • Rolando Cruz

  • Rory O’Reilly

  • Sergio Prado

  • Shaun Gibson