Setup for Mac and Linux Users

The suggested toolkit for Mac and Linux users is Multipass, a command line tool provided by Canonical that simplifies installation of Ubuntu LTS images.

If you are running Ubuntu 18.04 LTS as your host environment and have stock compiler versions, you may run the xv6 environment natively. In this case, skip installation of Multipass, SSH key generation, everything in Setup your Multipass VM, and everything is Connect VSCode to your Multipass VM, resuming with the steps in Setup xv6

Minimum Requirement

Mac

Mac OS Yosemite, version 10.10.3 or later installed on a 2010 or newer Mac.

Linux

KVM and the ability to support snapd

Installation Instructions

Setup Dependencies on your Host Machine

Confirm that your package manager is setup

For Mac, check that brew is installed by running brew help or install it
For Linux, check that snap is install by by running snap help or install it

Install Multipass

Mac:
```
brew install --cask multipass
```
Linux:
```
sudo snap install multipass
```

Install VSCode

Mac:
```
brew install --cask visual-studio-code
```
Linux:
```
sudo snap install code --classic
```

Install the following extensions:

Note: you can follow the links or simply run the commands shown below the links (easier)

Remote - SSH
C/C++
Live Share Extension Pack

x86 and x86_64 Assembly

via the following shell commands

code --install-extension ms-vscode-remote.remote-ssh
code --install-extension ms-vscode.cpptools
code --install-extension MS-vsliveshare.vsliveshare-pack
code --install-extension 13xforever.language-x86-64-assembly

Optionally, if you are coming from vim, emacs, or some other editor, and have a working muscle memory for those keybindings, consider installing a keymap extension.

Launch VSCode and confirm that the extensions have installed properly. You will potentially see installation messages on first start, including possibly a message prompting you to enter your user password to to install additional dependencies that the extensions require. Once this is complete, open the VSCode Extensions panel. You should see the extensions listed located under LOCAL - INSTALLED. If one of these extensions shows a Reload Required button, click it and wait for VSCode to reload.
Open Terminal and check if you have an SSH key on your system by seeing if ~/.ssh/id_rsa.pub exists. If you do not have a key, you can generate one with ssh-keygen -t rsa. If you do not wish to set a password, just hit ENTER when asked for a passphrase. You should now have a public / private keyboard located at ~/.ssh/id_rsa.pub and ~/.ssh/id_rsa respectively. If you generated a key, close and reopen Terminal to start a new shell session. You need to do this for ssh to be able to detect the presence of this new key.

Setup your Multipass VM

Generate a YAML configuration file containing your public key via the following:

cd ~
echo -n -e "ssh_authorized_keys:\n  - " > ~/primary-config.yaml
cat ~/.ssh/id_rsa.pub >> ~/primary-config.yaml

Create a Linux guest named primary. If you are on a system with more than 8GB of RAM, you may optionally want to increase the memory allocated to this VM from 1.5GB to 2GB by changing -m 1500M to -m 2G below.
```
cd ~
multipass launch -n primary -c 4 -m 1500M --cloud-init primary-config.yaml 18.04
```
You now have a Ubuntu 18 LTS VM named primary with a default user named ubuntu. Run multipass list to see that this is currently running and that it is the only VM listed.
Enter the guest by running multipass shell

Confirm that your VM has multiple virtual processors by running lscpu. Among others things, you should see:

CPU(s):              4
On-line CPU(s) list: 0-3
Thread(s) per core:  2
Core(s) per socket:  2
Socket(s):           1
NUMA node(s):        1

Set a User password. By default, Multipass does not require passwords, but some scripts require them. Run sudo passwd ubuntu and enter a new password
By default, multipass lets you access the Ubuntu shell via the command multipass shell. However, tools that enable remote development need to be able to use SSH. The public key you provided via the ~primary-config.yaml file should allow this. However, before we install VSCode, we should confirm that SSH works as expected, and to do this, we need to get the IP address of the VM. This IP address will change often as you start and stop your VM, so you will often need to figure out what this value is. With Multipass, there are two ways of doing this:
- In the primary guest, you can run ifconfig. The address will follow inet and look something like this 192.xxx.xxx.xxx
- In the host OS, you can run multipass list. The address is under the column IPv4.
Note the address from above, and then from a host shell, execute ssh ubuntu@<ip_address>, replacing with the address of your Multipass VM named primary. You should see a message like the following:

Depending on your distro and your SSH security settings, your system might cache fingerprints of known hosts that you've connected to in the past. This likely resembles a message like the following:
```
The authenticity of host '192.168.64.2 (192.168.64.2)' can't be established.
ECDSA key fingerprint is SHA256:EpXmNgNYL6wAICuQV+YaVjeTXwbGukzYh/U328lEmvI.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```
Enter yes, and you should successfully log into your guest. Enter exit to return to your host.

Note: Because your guest is dynamically allocated an IP, it is possible that it might be allocated an IP address that was previously used by a different host. If this occurs, you may see a security warning such as “WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!”. If this occurs, run vim ~/.ssh/known_hosts and clear out the offending entry. Once this is complete, you should be able to cleanly execute ssh ubuntu@<ip_address>.

Connect VSCode to your Multipass VM

Open VSCode and click on the green button in the bottom left corner. This should open a menu listing several Remote-SSH options. Click Remote-SSH: Connect to Host.... Enter ubuntu@<ip_address>, replacing with the address of your Multipass VM as before. This will open a new VSCode window. Feel free to close the old window. After a brief installation of the VSCode backend onto your VM, the bottom left corner's green button should now read: SSH: <ip_address>.
Hit ctrl+` in VSCode (Equivalent to selecting "View->Terminal" in the top menu), and ensure that the terminal in VSCode opens to your Linux home directory. It should show ubuntu@primary:~$
By default, the previous extensions you installed are running on the host operating system. However, some of these need to run on the remote backend running on your Linux guest. To address this, open the VSCode Extensions panel, and look under the heading LOCAL - INSTALLED. You will see several extensions that are grayed out and have a button Install in SSH: <ip_address>. Click this button for each extension.
You should now see these extensions under SSH: <ip_address> - INSTALLED. However, they likely have a button Reload Required. Once all extensions are installed under Ubuntu, click that button to reload the window. You will be prompted to install additional Linux dependencies, including prompting for your user password. When complete, you will be asked to reload VSCode yet again. Click “Reload Now.”

Install the necessary lilbraries

First, update the packages list:
```
sudo apt update
```
Run the following command to install the default ubuntu repositories:
```
sudo apt install build-essential
```
Run the following command to install the man pages:
```
sudo apt-get install manpages-dev
```
Run the following command to test gcc:
```
gcc --version
```

Appendix: Using Multipass

You can start and stop a vm; you can get a shell in the vm, run specific commands and get info from your image.

(From your host OS-shell) Starting:
```
multipass start primary
```
You should wait a few seconds until it is ready to use.
(From your host OS-shell) Stopping:
```
multipass stop primary
```
You should wait a few seconds until it has stopped.
(From your host OS-shell) Accessing the shell in the vm:
```
multipass shell primary
```
The last parameter is not needed if youo only have one image running.
(From your host OS-shell) Running a command in your vm without accessing its shell:
```
multipass exec primary <command> 
```
(From the guest OS-shell) Exiting:
```
exit 
```

Appendix: Multipass issues

Multipass may get stuck starting or stopping the image (primary). It happens sometimes when starting it or if it was not stopped properly. In those cases, shutting down and rebooting is your best shot (have you tried turning it off and on again?).

Appendix: Deleting and Rebuilding the VM

Currently, multipass does not provide an easy mechanism to modify the number of virtual processors and memory allocated to your virtual machine. As a result, if you underprovision the amount of memory assigned to your VM, your best bet is to delete, purge, and rebuild your primary VM. These instructions are intended to take you through that process. Please note that this deletes all data on this VM!

Log into you multipass VM and backup data that you are concerned with losing. Generally, this should only be assignments and labs, which should always be saved, committed and pushed to GitHub. If there is any data that you need to save, you can back this data up by copying the files/directories to your host filesystem. By default, multipass mounts your host machine's home folder at ~/Home.
Run multipass delete primary to delete your VM. This is recoverable and equivalent to placing the VM in your "Trash Can" on the desktop.
Run multipass purge to purge the data and "empty the Trash Can."
Run multipass list to confirm that your instances are purged
At this point, you should repeat the original setup instructions from the Setup your Multipass VM section onwards. Be sure to actually make the changes to the launch command that you care about! For the VSCode steps, you will not need to reinstall VSCode itself, but you will need to reinstall the remote VSCode backend and plugins on your Linux VM.

Appendix: Troubleshooting

Note: If you hit a snag, first try restarting your machine before proceeding.

The following script can be used to generate useful information to help the instructional staff debug issues:

#!/bin/sh

main() {
  echo "Mac Hardware:"
  system_profiler SPHardwareDataType

  echo "Multipass Info:"
  multipass info --all

  echo "Primary lscpu:"
  multipass exec primary -- lscpu

  echo "Primary lsmem:"
  multipass exec primary -- lsmem
}

main "$@"

CS 3410