Project 0: Installing and Getting Familiar with Minix

Summary
Due April 8, 2016, 11:59PM
Must be completed individually
Required before proceeding on to later Minix projects

This project is the basic introduction to Minix. You will download and install Minix on the emulator of your choice, recompile the kernel, and make a simple change to add some debugging facilities to your Minix installation.

Installing Minix
You'll start this project by first installing Minix 3.2.1 (note that 3.3 does not have the src directories, so we're stuck with 3.2.x for now). You can download the install CDROM image as an ISO file from the Minix project webpage. You will need to first decide how you will want to install Minix, on physical hardware (a real machine), or on a simulator/virtual machine such as Qemu, Virtual Box, Bochs, or VMWare. While a native install runs a bit faster, a VM install has the advantage that you can easily restart or reset machines, while not worrying about instability in your Minix code affecting the stability of your machine.

Personally, I've had good success using Qemu, which is a free (unlike VMWare) simulator that runs on all OS platforms. Qemu is also installed on CSIL already. To install your version of Minix, you'll need a fair amount of space. I've already requested sandbox accounts for all enrolled students on CSIL. This means that you should have an account under /cs/sandbox/student/yourlogin. Sandbox space is great, since there are no real quotas enforced. But the downside is that the space is *not* backed up, so you really want to save your edited files (source) elsewhere for reliability. I've seen too many projects ruined because of hardware failures or accidental 'rm -f'. Do yourself a favor and keep multiple copies. I strongly suggest running your own SVN server or git to keep reliable copies of your code. I've also requested github access for 170 students on the UCSB github server.

There is lots of available documentation online on how to install Minix. For installs on physical machines, take a look at the Minix install docs here. For installation on Qemu, there is a nice set of instructions here. Installing Minix is fairly straightforward, and involves several key steps:
1. partitioning harddrive
2. booting Minix from downloaded CD image
3. run the setup script
4. reboot from the installed Minix on disk

You’ll find that working on the projects is often easiest when you're physically at one of the CSIL machines. You can work remotely by redirecting the Qemu windows via either VNC or X11 tunneling over ssh. One word on VNC, it is not secure by default. Passwords and data is sent unencrypted over the network, so I highly recommend tunneling VNC over ssh if you plan to use it. We have had successful machine compromises based on VNC vulnerabilities.

Configuring Minix
Once you have installed Minix, there are a few things that you want to do to make the system more usable. The first is to get the network to work. The way how networking is set up depends on your target platform. For Qemu, you will probably want to use the user mode stack. The user mode stack does not require root privileges (and thus, is the only option on the CSIL machines) and should run basically out of the box. The only thing that might need to be fixed is the DNS name resolution. Similar to Linux, Minix uses the file /etc/resolv.conf to find DNS servers. Check the appropriate man page to determine the format of /etc/resolv.conf and provide a valid DNS server IP address. When everything works, you should be able to type host www.apple.com and get back a corresponding valid IP.

Once the network is active, you might want to install a few other applications to make your life easier. For example, you might want an editor (such as vim), openssh (to exchange files between Minix and the outside world), or a new shell (such as bash). Some of this might have been installed as part of your basic Minix package. Also, check out the source code of Minix that is located in /usr/src and get a feeling for which parts of the OS are located under which directories.

Once you get familiar with the system, answer these questions:

  • Provide a brief description of your installation, including whether on a simulator (and if so, which one) or on what hardware, and if on actual hardware, whether you have a dedicated machine or a machine that multi-boots Minix and other operating systems. Also (whether on real hardware or on a simulator), the size of your disk and the amount of memory available to the OS.
  • Why does a new installation of Minix come with an existing user called "ast"?
  • What is the name of the application (utility) that you used to install new software in Minix?
  • What is the command that you have to issue to rebuild the kernel and install it?
  • What is the kernel source file that holds the Minix banner string (i.e., "Minix 3.1.2a. Copyright ...") that is shown when Minix boots up?
  • What is the name of the Minix system call with the number 33 (decimal), and how did you determine this information?
Preparing a Minix Development Environment

 Now that you somewhat know your way around minix you need to prepare your development environment. Developing directly on Minix can be a huge pain, so you'll want to develop remotely, thus you'll need a convenient way to move files between Minix and your machine. Enter rsync. With rsync you'll be able to synchronize your minix folder to your development folder. In order to run rsync on a remote machine, you'll first need to install the openssh and rsync package on Minix. You should know how to do this by now.

After those packages are installed you'll need to reboot minix in order for the ssh daemon to run. Additionally you will need to figure out how to connect to port 22 on your virtual machine. If you are using qemu's user-mode networking, you can add the command line args -redir tcp:2222::22 which will allow you to ssh to minix from your local machine's port 2222. It is recommended that you copy your ssh public key to root's .ssh/authorized_keys file, and add an entry in your non-minix machine's .ssh/config file which allows you to ssh to minix simply by typing ssh minix. See this article for configuring ssh public keys. For the latter you can use the following as your .ssh/config file (assuming qemu): 
Host minix
    Hostname localhost
    Port 2222
    User root
Now that you can ssh into your minix VM via the command ssh minix, we need to create a few clean copies of the minix source code. This is necessary for two reasons. First, when you later make changes that do not work and you want to have a reference that you can look at, the source is already there. Second, and more importantly, you need a clean reference to create patches (see below). To do this, first create a clean copy on the minix machine: 
cp -r /usr/src /usr/src_clean
Now we need a copy of the code on your development machine. At this point, you should not be modifying any code directly on Minix. Run the following on your developement machine: 
rsync -rptOv minix:/usr/src/ minix_src_clean
Note that rsync may fail occasionally. If that happens, just continue to re-run rsync until you receive no errors.

Compiling and Modifying the Kernel

 Now it's time to rebuild the kernel. Before you make any changes you'll want to verify that you can successfully build and install a new kernel. Switch to the directory /usr/src/tools and type make. Check the options to see how a kernel can be rebuilt and installed. A small note: Once you have installed your kernel and restarted Minix, it is important that you select the second option "Start custom kernel" in the start screen. Otherwise, Minix won't run your freshly built kernel.

Note that it is recommended to be in the vanilla, or non-custom, kernel when you are transferring files to and from minix, and more importantly when you are compiling. To switch back to the vanilla kernel perform the following and make sure to select the first option: 
shutdown
boot d0p0
Now that you are able to build and load a new kernel it is finally time to make a small OS modification. First you will want to make a folder on your development machine for this project (note make sure to use rsync to make the copy and not cp as otherwise the timestamps of the files will be updated): 
rsync -rptOv minix_src_clean proj0
For the kernel modification itself, I want you to print out the name of every file that is being executed by the OS. You will need to locate the kernel source file that implements the exec system call. Then, at the right point, you should insert a printf statement that outputs the string "executing ... " followed by the name of the file that is being executed. That is, when you type "ls" in the shell, you should see the string "executing ... ls" being printed to the console. This should actually require only a single line to be added, but it provides you with some (very basic) debugging facilities. Once you have done your modification, you will need to first rsync your changes back to minix. That can be accomplished by: 
rsync -rptOv proj0/ minix:/usr/src/
Note that the argument order (source and destination) are important. At this point you should never have to rsync anything from minix thus you should always use this command to synchronize. Also, like before, if you encounter any errors, just continue to repeat the command until it succeeds.

Once you have synchronized your files remotely switch to your minix machine, rebuild the kernel, install it, and reboot the system. If you were successful, you should now see a series of output statements that show you which programs the operating systems launches.

Creating a source patch to submit

 Your last task is to submit your changes to us. Clearly you don't want to submit entire code-trees when submitting a project. Instead, you'll want to submit a set of code patches for the files that you modified in your work. A patch captures the changes between two different files (oldfile and newfile). Given the oldfile and the patch, one can use the patch program to create the newfile. This is exactly what we want. So, when you have finished your kernel modification (including recompiling, installing, and testing everything), perform the follwoing: 
diff -ruNp minix_src_clean/ proj0/ > patch
This will create the file patch, which should only contain lines you intentionally modified. For this project the patch file should contain no more than 15 lines. You can test whether your patch has worked by creating another copy of the source tree and running patch as so: 
cp -r minix_src_clean test
cd test
patch -p1 < ../patch
Note that this is how we test your patches, and we expect that they can be applied cleanly (without any warnings or errors).


Submission Process
Your submission must be submitted prior to the deadline in order to be graded. Do a man turnin to find more info about the turnin program.

To submit:
  • Ensure your current working directory is a directory containing:
    • a file named answers.txt that includes answers to questions listed above
    • a file named patches that contains the patch to the Minix kernel to print the requested debug information (see above). The patch must apply cleanly to a fresh source code tree.
  • Execute the turnin program: 
    turnin proj0@cs170 answers.txt patch

You can execute turnin as many times as required. The most recent submission prior to the deadline will be used for grading. Note that you CANNOT use your extension days for project0.