Due: Wed Jan 14 11:59 pm
Late submissions accepted until Sat Jan 17 11:59 pm.

We will discuss the terminal and text editors on January 7^th, and you'll need that material to complete the assignment. You can, however, configure your laptop to ensure it has a working terminal, review the course syllabus, and complete the honor code survey we link to below.

Assignment by Michael Chang, Julie Zelenski, and Chris Gregg, with modifications by Nick Troccoli

Learning Goals

The goals for this assignment are for you to get familiar with working in the Unix environment, and editing/building/running C programs.

Unix and C Resources

The pages in the Handouts dropdown above include information detailing the various Unix commands and tools we'll be relying on this quarter. We recommend reading over Getting Started on Myth and Unix Guide before delving into the content of assign0. Many assign0 tasks leverage material outlined in those two handouts. You don't need to memorize any of it for testing purposes, though you'll start to given how often you'll be using some of the most common commands.

Before beginning, confirm you're comfortable with the fundamentals as discussed in the Getting Started with Unix guide.

View Getting Started Guide

• Log in to a myth machine
• Manage files, navigate the filesystem
  • Did you create a CS107 directory to house all of your work?
  • Can you find the code we're showing during lecture?
• Edit files, configure your text editor
  • You should be able to create a new file, edit its contents, save, and exit.
  • For emacs, you should be able to interact via the mouse (e.g. selecting text, scrolling, etc.)
• Working with the shell and common Unix commands
  • If you come across a new command, how can you get information about it?
  • Have you tried using tab-completion to avoid manually typing long commands/paths?

Take a look at the guide in the Assignments dropdown that talks about how to best work on your assignments. We will refer to this document many, many times throughout this assignment, so keep it open as you work through it.

View Assignments Guide

Cloning The Assignment

To get started on the assignment, you must clone the starter code to get a copy you can work on. Check out the assignments guide for how to do this.

If you attempt to clone and receive an error that the repository does not exist:

• double-check for typos in the path. The path needs to be typed exactly as specified. This includes the odd-looking $USER at end, which is a environment variable that automatically expands into your username.
• be sure you are logged into myth.

If your attempts to clone generate a dubious ownership error message, make sure you run the setup.py script discussed at the top of the Assignment Guide document.

If you're indeed on myth machine and your correctly typed path isn't there, that means you weren't enrolled at the time we generated all of the student-specific repos. Send an email to the course staff and tell us your official SUNet username so we can create a repo for you. Please make sure to enroll in Axess as soon as possible so that repos are generated for you from assign1 onward.

Provided Files

The starter project contains the following:

• readme.txt: a text file where you will answer questions for the assignment
• triangle.c , Makefile and custom_tests: used to build and test the triangle program
• samples: a symbolic link to the shared directory /afs/ir/class/cs107/samples/assign0. It contains:
  • SANITY.ini: the configuration for sanitycheck. You should ignore this file.
  • server_files: a folder that pertains to the first part of the assignment.
  • triangle_soln: an executable solution for the Triangle program. You can run this program to see how a completed solution program should behave. This program is also used to check correctness in sanity check.
• tools: contains symbolic links to the sanitycheck and submit programs for testing and submitting your work.

Symbolic links mean that the files actually live in the CS107 class directory, but appear just like normal files in your starter code folder. Note that the shared directories are not editable by you, so you will not be able to create, edit, or delete files within these directories, since they actually live in the CS107 class directory.

1. Enrollment Confirmation

In order to complete your enrollment in CS107, you must fill out the readme with some information about you, confirm your ability to attend the final exam and accept the course Honor Code policy.

Open the readme.txt file in your editor now and edit as appropriate.

As part of this, you must complete the Honor Code Form. When grading your assign0, we will check that you made a submission through this form, so please make sure to fill it out!

Access the Honor Code Form

Course TODOs:

Once you have done this, also complete the following setup tasks:

1. Join our course discussion forum by visiting the Getting Help page.
2. Remember to submit your lab preferences (not first-come-first-serve) between Mon Jan 5 10:00 am PDT and Sun Jan 11 5:00 pm PDT.

2. Intruder Detection

For this activity, you will investigate a simulated break-in and answer the questions below. Type your answers into the readme.txt file. For each, briefly describe (in 1-2 sentences) how you arrived at that answer and what Unix commands you used (text editor keyboard shortcuts (e.g. emacs commands) do not classify as Unix commands).

Activity Learning Goals: In class we have taught you the basics of Unix: how to login to myth, how to make directories, and how to list files. In this activity, you will further develop your Unix skills by understanding how to use common Unix commands beyond what we know so far. The how-to's of many of the commands you will learn are available on our CS107 Unix guide, under "Handouts". We recommend you browse this guide as you complete this activity:

View Unix Guide

Situation: An intruder had broken into your dorm's unix-based server and deleted most of the files! Fortunately, there is a backup of the server contents, but before restoring the files, you'd like to know who the intruder was and what they did. With your newly-developed Unix skills, you are just the expert to help investigate.

The key files are available in the directory samples/server_files, which you can access within your assign0 directory.

The first thing you want to determine is the username of the intruder. The server is used by many different users. Each user has a home directory under home/. For example, the home directory for the user bob would be the path home/bob. The file users.list contains a list of all the authorized users. In an uncompromised system, each home directory would correspond to a user on the authorized list and vice versa. The intruder is not an authorized user and they gained illicit access by inserting their own home directory onto the system. This means there is one home directory that doesn't belong, and your job is to find it.

Manually cross-comparing the users.list to the directory contents would be time-consuming. Instead, what Unix commands can you use to help? Check out the Unix guide for some ideas.

Hint: the samples/ folder and everything inside it is a shared, read-only folder for all students for this assignment. For this reason, you can't create any new files within samples, and you can't create new files outside of samples from within the samples folder. If you need to create a temporary file, try creating it directly inside your assign0 directory instead.

1. What is the username of the intruder? Include the details on how you figured out the answer, and what Unix command(s) you used. You should use Unix commands as much as possible, even if other by-hand alternatives exist (as a clarification, commands within a text editor - e.g. emacs - are not Unix commands).

Now that you know the intruder's username, you can examine the files in intruder's home directory to learn what they were up to. Though the intruder tried to delete all the home directory files as part of covering their tracks, you can see that this supposedly empty directory is still taking up space. Perhaps something interesting was overlooked?

Take a closer look to find out what files have been left behind. Open each of the files in the intruder's home directory to see their contents.

2. There is one file in the intruder's home directory that provides critical information about their activities. What file is that and what does it contain? Include the details on how you figured out the answer, and what Unix command(s) you used. You should use Unix commands as much as possible, even if other by-hand alternatives exist (as a clarification, commands within a text editor - e.g. emacs - are not Unix commands).

You believe that the intruder used sudo to execute some commands as a privileged user. You want to identify those commands, but the file is rather long to comb through by hand. What Unix command can you use to extract the information you seek?

3. Which commands did the intruder execute using sudo? Include the details on how you figured out the answer, and what Unix command(s) you used. You should use Unix commands as much as possible, even if other by-hand alternatives exist (as a clarification, commands within a text editor - e.g. emacs - are not Unix commands).

3. C Introduction

The final task of the assignment gives you practice using the Unix development tools to edit, build, run, and test a short C program.

In your assign0 folder, type make. This will build the program named triangle. Run the program to see what it does:

./triangle

You should be rewarded with an ascii representation of Sierpinski's triangle - cool! Try to run make again:

myth$ make
make: Nothing to be done for `all'.

This isn't an error; it simply means that nothing has changed in the program's source, so there isn't anything to re-compile.

Open triangle.c in a text editor and change the value of the #defined value, DEFAULT_LEVELS above main from 3 to 5. After you have saved the file, you must then use make to re-build the program, and then you can run the newly built program to see the bigger triangle. If you forget to re-run make, you will run the original version of the program that has not been updated!

The starter code uses a fixed constant for the number of levels to print. Your task is to extend the program to take an optional command-line argument that allows the user to dictate the number of levels. With no arguments, ./triangle should default to a level 3 triangle, but the user should also be able to provide a numeric argument, e.g. ./triangle 4 or ./triangle 2, to control the number of levels. If given an unworkable number of levels (anything larger than 8 gets unwieldy and negative would be nonsensical), your program should reject it with a helpful and explanatory message that informs the user how to correct their error, and then terminate early with an exit status of 1 (this indicates something went wrong with the program execution). The best function to do this is the error function! Type man 3 error for more information about how this function works.

Oh, and fun fact: there are man pages for both Unix commands (e.g., man ls) and built-in C functions (e.g., man strcpy).

Incidentally, you should specify an error number of 0, since we don't need to print some error code-specific message. Try to figure out the values for the remaining parameters. You must exactly match the error message of the sample solution. Note: You may assume that the user will enter an integer value, and do not have to worry about handling arguments that are not valid integers. If the user specifies multiple command-line arguments, you should use just the first one.

When applicable, you should define constants rather than rely on "magic numbers", which are numbers hardcoded into your program. See the starter code for an example of how to do this in C.

In order to complete this task, the program will need to convert the user's argument (supplied in string form) into an integer. The C library function atoi can be used to do this. Review the man page (man atoi) or look in your C reference to get acquainted with this function.

Testing

Now let's test the program implementation. The sanitycheck tool is included in the assignment starter project, and acts as a testing aid. Read the guide to working on assignments for more information about how to use it.

The default sanitycheck for assign0 has one test that validates the output of the triangle program when given no argument. The unmodified starter program code should pass this test. After you have extended the triangle program to accept an argument, the program should continue to pass the default sanitycheck, but you will need new tests to validate the argument handling.

You extend sanitycheck to test additional cases by using a custom tests file. The starter project includes a custom_tests file. Open this file in your editor to see the format. Now consider what additional test cases are needed to fully vet the output of your new, improved triangle program. You must provide at least four additional tests. These additional tests should exercise edge cases that a well-intentioned implementation could in theory miss! Add those tests to this custom_tests file and use these with sanitycheck to validate that your triangle program passes all tests. For more information about how to run your custom tests, check out the guide to working on assignments. For tips on thorough and meaningful testing, check out our testing guide, linked to from the assignments dropdown.

Submitting

Once you are finished working and have saved all your changes, check out the guide to working on assignments for how to submit your work. We recommend you do a trial submit in advance of the deadline to familiarize yourself with the process and allow time to work through any snags. You may submit as many times as you would like; we will grade the latest submission.

You should only need to modify the following files for this assignment: readme.txt, triangle.c, custom_tests.

Grading

The assignment is graded out of about 26 functionality points, plus a bucket grade for style. Full credit will be awarded for reasonable answers to the questions in the readme.txt file and a correct modification of triangle.c and custom_tests. This assignment is worth far fewer points than all of our other assignments. But, hey, we expect each and every one of you to earn all of the points on this one!

Post-Assignment Check-in

How did the assignment go for you? We encourage you to take a moment to reflect on how far you've come and what new knowledge and skills you have to take forward. Once you finish this assignment, you should have your environment configured and should be starting to feel comfortable with the command-line interface, navigating the filesystem, using a Unix text editor, and getting around Unix. You're off to a great start!

To help you gauge your progress, for each assignment/lab, we identify some of its takeaways and offer a few thought questions you can use as a self-check on your post-task understanding. If you find the responses don't come easily, it may be a sign a little extra review is warranted. These questions are not to be handed in or graded. You're encouraged to freely discuss these with your peers and course staff to solidify any gaps in your understanding before moving on from a task. They could also be useful as review for our exams.

• Identify a few different techniques to avoid painstakingly re-typing a long Unix command to execute.
• How do you copy and paste in your text editor?
• Explain the purpose and use of the CS107 tools sanitycheck and submit. How do you customize the tests used by sanity check?

Frequently Asked Questions

When I try to run the triangle program in my directory, it responds "command not found". What's wrong?

Unix wants you to instead refer to the program by its full name ./triangle. See our Unix guide for more information.

How do I use the sample executable? How does it relate to sanity check?

Our provided sample executable can be used a reference implementation during testing. Run the solution and your program on the same input and verify the output is the same:

myth$ samples/triangle_soln 4
                ... solution output is here ...
myth$ ./triangle 4
                ... your output is here  ...

If your program produces the same result as the sample, all is good. You can manually "eyeball" the two results, or run sanitycheck with the provided tests, or your own tests. You can find more information about sanity check in our guide to working on assignments.