Lab 1: Linux Setup

When you're done with this lab you will have done the following things:

  1. SSH to your CSSE132 ARM64 virtual machine (VM) and clone your CSSE132 Git repo.
  2. Compile and run some ARM assembly.
  3. Practice basic Linux commands.
  4. Fix a broken image by hacking the raw binary file

Part 1: Git on Linux

Goals of this section:

If you haven't yet, please complete the prelab.

Claiming a VM

Go to this Google sheet: CSSE132 VM signup. Write your RHIT username in an open slot. (Just one, and please don't overwrite another student's username.) Remember your VM hostname (e.g., csse132-01) and go on to the next step.

SSH to your VM

Important Note: To connect to your CSSE132 VM, or the department Git server gitter, you must be behind the RHIT network firewall. That is, you should either (1) be on campus connected to the campus network via WiFi/ethernet, or (2) from off campus, be connected with the RHIT VPN. See EIT instructions for how to use the VPN.

Use the SSH protocol to connect to your VM. The VM's username is csse and you'll use default password change (unless you've already changed the password in the setup step). Also remember your VM's hostname from the above step, and the VM is run by the RHIT CSSE department, so the complete network address is <hostname>.csse.rose-hulman.edu. For example, in Git Bash, you can use the command

     ssh csse@<hostname>.csse.rose-hulman.edu
  1. You may be asked to add an ECDSA signature key, if so, say yes. If the SSH command complains that the key differs from a known key, use the command ssh-keygen -R <hostname>.csse.rose-hulman.edu (with your hostname) to remove the old entry and then retry the ssh command.
  2. Note that you won't see your password on the screen as you type it, for privacy reasons (if someone was looking over your shoulder). If you mess up while typing, you can always hit delete a bunch of times and then start over.
  3. When you first connect, the system will force you to change your password. It prompts you for the current password (change) and then asks for a new password. Please choose a password that is personal to you and not easily guessed.
  4. You will then need to log in again (hit up-arrow, then enter, to repeat your ssh command) with your new password.
  5. Here's what it looks like when you're connected:

Now it's time to play around with Linux in your terminal. For the rest of this lab, you're going to use a number of Linux commands. Here's a quick reference for some of them:

Also, in order to run things as an administrator (for example, to install programs), you need to use a command called sudo. This temporarily turns you into an admin called root. Try it!

csse@csse132-01:~$ whoami
csse
csse@csse132-01:~$ sudo whoami
root

Install Git

Next, you need to install the git client so you can get your lab and homework materials. Use apt to install it!

user@hostname ~ $ sudo apt install git

NOTE: your Linux may already have Git installed. If it does, running this command will result in a message such as:

git is already the newest version

Configure Git

Next, you will have to tell Git your username and email address. Use the git config command to do this.

git config --global user.name "YOUR NAME"

(replace "YOUR NAME" with your name, like Chauncey Rose)

git config --global user.email youremail@rose-hulman.edu

(replace "youremail@rose-hulman.edu" with your Rose email address).

Use Git

Clone your class repository on the VM

Clone your repository using a command like this, replacing <username> with your RHIT username. NOTE: <username> appears twice; replace it both times. From your terminal that is SSHed to the VM, in your home directory (type cd ~ first if needed), use the git clone command:

git clone ssh://<username>@gitter.csse.rose-hulman.edu:13022/srv/repos/2425c-csse132-<username>

Use your RHIT password when asked for a password.
NOTE: GIT may ask you if you want to accept a key. Type "yes" to accept.

Once it's checked out, use the cd command to go into the directory, and the ls command to show your repository's contents. HINT: you can type part of the command (like cd 2425 and then hit tab to auto-complete the directory).

csse@csse132-01:~$ cd 2425c-csse132-username/
csse@csse132-01:~/2425c-csse132-username$ ls
lab1
csse@csse132-01:~/2425c-csse132-username$

Note: if you don't see the lab1 folder, try (within the repo directory) typing git branch. If no branch is reported, then try switching to the main branch with git switch main. Then repeat the ls command to make sure the lab directory appeared.

Create and push a new file.

Use the cd command to go into the lab1 folder. Once you're in there, create a new file called "name.txt":

  1. Type echo "MY NAME" > name.txt to create a new file with your name in it (replace MY NAME with your name, like Chauncey Rose)
  2. View and print out the contents of the file: see what happens when you type ls. Then try cat name.txt

Now that you've got the file, commit it to your git repository. First, pull any changes from the server:

git pull

Then, you need to tell git about the file:

git add name.txt

Commit your changes:

git commit -m "added new file in lab 1"

Once it verifies your commit, it's time to upload your new file to the server.

git push

You've committed your first git file! Good job!

Clone your class repository on your laptop

Open up a new Git Bash window. In this terminal, do not SSH to your VM: rather, we will work on your local machine.

The Git Bash terminal provides a Linux-like interface on your Windows machine. The Git Bash home directory ~/ maps to your local home directory in Windows Explorer, i.e. This PC > Local Disk (C:) > Users > username. Navigate to a folder (using cd, pwd, ls, etc.) where you'd like to keep your CSSE132 Git repo locally. Then repeat the git clone command from above to clone another copy of your repo. Make sure that the clone succeeded by viewing your lab1 file.

You will need to drag and drop files from this folder to Gradescope in the future. So it is highly recommended to bookmark this folder.

You only need to clone once. Now that you have clones on the VM and on your Windows machine, your general workflow will be: 1. Make changes to files in Linux on your VM 2. On your VM, use git add to add any files to the commit, followed by git commit to make the commit locally, then git push to send the commit to the remote gitter server. 3. In your Windows system, use Git Bash to git pull on your local repo: this fetches changes from gitter. 4. Upload any files from your local repo to Gradescope via your web browser.

SAVE A SCREENSHOT TO SHOW YOUR INSTRUCTOR LATER

No worries about calling out your instructor for signature yet. Save a screenshot of your local Windows directory (in Git Bash or in Windows Explorer) showing the file name.txt that you created earlier on the VM. When you finish more items, you can show to your instructor all at once. -->

Part 2: Get Linux Ready for ARM Assembly

Compile and Run an ARM program

Go back to your VM terminal. In your git repo, navigate to the hello_ARM folder inside the lab1 folder. This can be done with the following command (replace username with your RHIT username)

 csse@csse132-01:~$ cd  ~/2425c-csse132-username/lab1/hello_ARM

Using ls, you can see the files in this directory:

csse@csse132-01:~/2425c-csse132-username/lab1/hello_ARM $ ls
Makefile hello.s

The hello.s file contains ARM64 assembly code. View it with 

cat hello.s

Assembly code is "human-readable machine code". To make it to actual machine code (or object code), we need to assemble. Try the following command. The -o hello. o part tells the assembler to call the object file hello.o.

as hello.s -o hello.o

When you now ls, you should see a new file hello.o. What happens when you try to print its contents using cat? (Note: this is human-unreadable machine code!) The object code is not executable until it has been linked with any necessary libraries, other object files, etc. using the linker. Try the next command.

ld hello.o -o hello

This creates an executable, hello. Run it with the command 

./hello

Take a look (cat) at the other file, Makefile. Makefiles are used by developers to ease the workflow of many Linux tasks, especially compiling code. Try typing make clean, and then run make. Note what files get removed, then created. What happens if you run make again when the code hasn't been modified?

SAVE A SCREENSHOT TO SHOW YOUR INSTRUCTOR LATER

No worries about calling out your instructor for signature yet. Save a screenshot of the "hello message" for now. When you finish more items, you can show to your instructor all at once.

Part 3: Learning and Practicing Linux Commands

Open a web browser and go to the bandit instruction page using the link below:

http://overthewire.org/wargames/bandit/

Follow the instructions and get into level 5. After finishing each level, save the password on your computer (e.g., in notepad). You will need to provide this info in the verification sheet.

Hint: After you finish each level, you can press Ctrl + D to logout of the current session/level. Then, you can press Up-Arrow to get the ssh command,
change the account name (i.e., bandit0) to the new bandit number (i.e., bandit1), and use the new password to log into the next level.

Part 4: Fix an Image

Finding the image: Go to your Windows File Explorer and navigate to the lab1 folder in your CSSE132 Git repo where you should find the lab1_broken_pic.png file.

This file has corrupted data. In this part, you will tweak the data of the image file to repair it. To modify the raw data of a file, you need special tools. Frhed is a free binary file editor available on Windows. Follow the link below to download the tool:

Frhed Download Link

Usage:

Wrong Format

PNG defines a certain format that a picture file has to follow. If a picture does not strictly follow this format, computers can not recognize it correctly, and thus fail to open it as a picture. This is what happened for this picture.

To fix it, you need to first understand the format specs of PNG. Check the PNG Format Specs page and particularly focus on the File Header section.

Now, open the lab1_broken_pic.png (the one you copied to Desktop), and inspect the header (the few bytes at the beginning) to see if it matches the format specs in the Wiki page. Fix the incorrect byte.

If you successfully correct the header, the picture can be opened as a picture to view. However, since the size information is incorrect, when you open this picture in apps like Paint, you will see some white margin underneath the picture.

Wrong Size

When opening the picture, you will see extra white space below the picture. That's because the size specified in the file is not correct, specifically the height is too big. (You can find the size information by right clicking the file -> Properties -> Details Tab.)

Check again the PNG Format Specs to find the bytes that define the height.

Hint: After the header, comes a series of chunks, each of which conveys certain information about the image. The height is defined in the IHDR chunk, the very first chunk of the file.

Once you find the bytes that define the height, change it from 666 to 410. First, convert these two numbers to hex and then edit the bytes accordingly.

If you did that, your image file should have the correct size. If you open it in Paint, you will see the white margin removed. If you are using Linux as the host OS on your laptop, after you modified the size, the picture will appear to be broken again because the CRC is incorrect. However, if you use Windows, the picture is still viewable because Windows doesn't care about CRC.

Fix the CRC (Optional)

The reason it should break is because the software should notice we edited (corrupted) the file so it should consider the file is not safe. The way the computer detects this problem is to use certain bytes in the file to calculate a validation code, called CRC (cyclic redundancy checksum). It will compare the computed result with the checksum stored in the file. If the result doesn't match, it knows the file is corrupted. In our case, the CRC for the IHDR chunk is not correct given the modified height info. To find the the CRC, pay attention to the "offset" shown at the bottom left corner of the app: the first byte of CRC is at the offset/address 0x1D.

We need to re-calculate the CRC. Once we know which bytes we need to use to generate the new CRC, we can simply use this website CRC calculator to calculate new CRC. Based on the specs, we know the CRC for this chunk is calculated over the chunk type and chunk data (Hint: from offset 0xc to 0x1c). To use this website, you need to select CRC-32 first. Then you need to copy the bytes using the format like 0x31 0x32 0x33 0x34 ..... Once you calculate the new CRC, update this new CRC in the file.

Once you have done that, the picture will have the correct CRC and can be opened on Linux. On Windows, there is no visual difference after fixing the CRC.

SHOW YOUR INSTRUCTOR

Now it is a good time to call your instructor to check all the items at this point off the Instructor Verification Sheet.

Finishing the Lab

  1. Scan and Upload the signed instructor verification sheet to Gradescope.