Welcome to the class! Setting up a Linux environment is required for the course,
and this assignment will serve as a guide to get you started.
Use this as an opportunity to introduce yourself to the class, and get your feet wet with the git send-email
patch submission process we'll be using.
Patch 1 adds username/setup.txt
containing the content described below
Don't forget a cover letter
All email code patches are expected to pass checkpatch.pl
as described in the policies and procedures
Submit your patches to setup@COURSE_DOMAIN
Start by downloading the standard ISO image for Fedora Server for your architecture. You'll likely want the ISO for x86_64 unless you have an M-series Mac, or you are running Linux on ARM, in which case you want the aarch64 ISO. The ISO is large, so the download may take a while depending on your internet speed.
Next, download and install hypervisor software for your operating system:
Windows - VirtualBox:
MacOS - UTM:
Linux - virt-manager:
Once the ISO image has finished downloading, you can begin the VM set-up process. The exact procedure will vary depending on the software you're using, but the core idea is that you'll want to create a new virtual machine guest and decide what portion of your machine's resources to allocate to the VM.
Most likely you can follow the set-up wizard of your software for creating a new guest and end up with a working machine, but you probably want to increase the default values for RAM, CPU cores, and disk space. The more you can give the VM, the better, but a good rule of thumb is to leave at least half of your cores and RAM for your host system.
Feel free to reach out for specific advice depending on your machine.
Be sure to allocate at least 50G for the virtual hard drive.
At some point in the setup process, you'll be prompted to attach the ISO image to the machine, which will allow it to boot into the Fedora live environment. You can then start the VM for the first time and it will boot the Fedora ISO image.
Once the VM boots you will see a grub menu with two options:
test this media and install fedora
install fedora
You can select either one; testing the media will verify that your ISO downloaded correctly, but it will take longer.
Once the actual operating system boots, the Fedora installer should open automatically. Before you begin the installation you must resolve the two items with orange warning icons shown in the below image:
Click on Root Account, enable it, and then set up root with a password you'll remember before clicking "Done"
Click the Installation Destination icon, then click "Done" in the resultant menu
If you get stuck, there are numerous tutorials online on how to proceed based on the VM software you are using. Note that on Fedora 40 you may see "User Creation" with a similar warning icon, but that warning will be resolved when you configure the root account, and can be safely ignored.
Once the installation has finished, Fedora will tell you to reboot. Shut down the machine and remove the ISO image from where you attached it to the VM (once this is done and you confirmed the installation was successful, you can remove the ISO image from your host machine to free up disk space).
Next, boot up the VM. You should be greeted with a Fedora login prompt; use the username "root" and then enter the root password you selected during installation (it won't look like you are typing any characters when you enter the password, but they are being received--hiding them is just a security measure).
If you logged in correctly, you should be greeted with a command prompt that looks something like:
[root@localhost ~]# _
If you see this, you have completed the basic installation of Fedora correctly. Congrats!
First, set a hostname for the machine. While logged in as root, run the following commands:
echo your-hostname > /etc/hostname
where you replace your-hostname
with whatever name you'd like to use (e.g. joels-fedora-vm
)
hostname --file /etc/hostname
to update it without needing to restart the machine
To verify, log out, and the login prompt will include the new hostname before the word login
(e.g. joels-fedora-vm login: _
).
You'll then want to run a software update. While logged in on your root account,
run dnf update -y
(this may take a while), and reboot when it completes.
If you'd like to continue following these steps instead of waiting for this to complete,
you can switch to a different console by pressing ctrl+alt+f2
(on some keyboards you might need a function key to press f2), which will open the second tty.
You can check back on the update any time by pressing ctrl+alt+f1
, which will switch you back to your original tty.
The next step is to create a non-root account for yourself with sudo permissions. While logged in as root, run
useradd username
where username
is whatever username you'd like to have
usermod -aG wheel username
to give username
permission to run commands as the superuser (root)
passwd username
which will prompt you to create a password for username
You can then log out of root (type exit
or hit ctrl+d
)
and try to log in as your new user with the username and password you selected.
Once logged in, you'll want to verify that you have root access. Running sudo whoami
should prompt you for a password which, once entered,
will allow the whoami
command to execute and output root
.
Although you allocated the requisite 50+G of space, Fedora defaults to only using 15G for your filesystem. You can resize it to use all available space with:
lvextend -r -l +100%free /dev/fedora/root
At this point, you can go no further without dnf update -y
finishing.
If it's still running, let it finish, reboot, and then continue.
Login as your non root user account, then run sudo dnf install -y git git-email
to install the necessary packages for this step.
When this has finished, configure your .gitconfig
, which lives in your home directory ~/
, using a text editor (e.g. nano ~/.gitconfig
or vi ~/.gitconfig
).
You can pick your default editor by adding
[core]
editor = nano # Or which ever editor you prefer
then set your identity and account information by adding
[user]
name = Your Name Here
email = YOUR_USERNAME@COURSE_DOMAIN
[sendemail]
smtpUser = YOUR_USERNAME
smtpPass = YOUR_PASSWORD
smtpserver = COURSE_DOMAIN
smtpserverport = 465
smtpencryption = ssl
Make sure to fill in the fields with your class username and password (the ones you use to log into the course website).
Next, clone
the assignment git repository.
Use cd
to enter the directory, then mkdir your-username
, to create a directory in the repo, where your-username
is the username you use to log into the course website.
Add a file named setup.txt
to this folder containing an introduction about yourself.
The content can be whatever you want, whether it be why you are taking this class, your favorite ice cream flavor, or a fun fact about yourself.
Now, run:
whoami >> setup.txt
to append your chosen local username
uname -a >> setup.txt
to append a line with information about the VM environment you set up
df -H >> setup.txt
to append your available disk space
When you're done, make a commit out of your changes.
By default git will not be tracking changes to newly created files.
Add your file to the list that git is tracking with git add setup.txt
, then
make a commit to save this version of the repository so it can be shared with git commit -s
.
Note that the -s
flag makes git include the Signed-off-by
DCO line for you automatically.
Git will then open an instance of your preferred text editor to let you input a message for the commit.
Put a title containing a short summary of what you did on the first line,
e.g. Setup: Added introduction for so and so
.
Press enter twice,
and then write a more detailed explanation that will act as the body of the commit.
There should already be a Signed-off-by
line for your account at the bottom. If not, add one, then save your changes and exit the editor to finish the commit.
Check to make sure you see the commit and it looks good by running git log -p
.
Your new commit should be the top most one, and you should see the title, message, DCO,
and difference view containing the changes.
If there is more output than can fit on one screen, git will open a scrolling view that you can maneuver up and down within using the arrow keys. Press q
to go back to the terminal.
Next, you'll want to create a patch series with a cover letter out of your commit.
To do this, run git format-patch -1 --cover-letter -v1 --rfc
-1
includes the most recent 1 commit
--cover-letter
generates a cover letter for the whole patch series with a summary
-v1
marks this as the first version of this patch set
--rfc
marks these patches as a request for comment, which is required for all initial submissions (since they will be receiving peer feedback)
The result of this command should be your directory containing two new .patch
files,
courtesy of git.
You'll want to open the first of these, v1-0000-cover-letter.patch
,
in your text editor so that you can write your cover letter according to the
assignment submission guidelines.
Don't forget to add the Signed-off-by
line at the end of they body.
Once you've finished your cover letter, send your patches to the class mailing list.
You can do this by running the command
git send-email --to=setup@COURSE_DOMAIN v1*.patch
.
Each assignment will have its own special address to send submissions to, in this case setup@COURSE_DOMAIN
The expression v1*.patch
will be expanded by the shell into all file names matching
that pattern (any file whose name starts with v1
and ends with .patch
)
git send-email
will prompt you to ask whether it should send the emails, typing a
and hitting enter will send them all
If it is successful, the output should end with Result: 250
which indicates that the server accepted your emails.
If not, do not hesitate to reach out in #questions
on the course Matrix so that we can help with troubleshooting.
While logged in as your non root user account, install mutt
(a terminal program for viewing email) by running sudo dnf install -y mutt
.
Next, configure your .muttrc
which lives in ~/
, using a text editor (e.g. nano ~/.muttrc
or vi ~/.muttrc
).
First you'll want to set your identity and account information by adding:
set realname="Your Name Here"
set my_username="YOUR_USERNAME"
set my_password="YOUR_PASSWORD"
set my_domain="COURSE_DOMAIN"
Fill in your credentials that you use for the website and your full name. Next, set some sane defaults, and configure the server addresses by adding:
set spoolfile=
set record=
set folder=
set sort=reverse-threads
set from="$my_username@$my_domain"
set header_cache=~/.cache/mutt
set smtp_url="smtps://$my_username:$my_password@$my_domain:465"
push "<change-folder>pops://$my_username:$my_password@$my_domain:995"\n
macro index l "|git am -s"\n
Copy that block in verbatim
and mutt
will substitute the variables you set in the previous declarations for you.
Once that's out of the way, open the email list by running the mutt
command.
In mutt
, you will see a list of email threads, which should begin
with a "welcome to the email system" message,
followed by all subsequent emails in chronological order.
Press:
enter
to view which message you have highlighted
q
while viewing a message to exit back to the main screen.
space
to scroll to the next page within the email.
q
or ctrl+c
to exit mutt
.
Before the initial submission deadline, you will see no messages. Following the deadline, all submissions are revealed and peer review begins.
If your git send-email
output ends in Result: 250
then, congratulations! You successfully completed the setup.
After submitting all later asssignments, you can check the course dashboard to make sure your submission was successfully received.
You may decide you'd like to better prepare your VM for the remainder of the course. Here are some recommended steps you might take:
Set up SSH access. While logged in to the machine on the tty,
run the command ip -br a | grep UP
and read the ip address listed there.
On your host machine, open a terminal and try running ssh username@ip-address
where username
is the username you picked earlier and ip-address
is the one you just found.
The first time you connect to a new server,
ssh
will not know the server and will say it cannot establish the authenticity of the machine you are connecting to, asking if you are sure you want to continue connecting.
Type yes
and hit enter.
You will be prompted for your password--this is the password for your account on the VM.
Once entered, you will be able to access your VM from your host machine
through a shell exactly like the tty you get by logging in within the VM window.
You can log out by typing exit
and hitting enter, or pressing ctrl+d
just like the tty.
If you want to obviate the need to enter the password every time you log in, you can set up SSH-keys.
Open a terminal on your host machine (cmd.exe
on windows).
If you have never set up SSH-keys (you might have done it already if you use ssh for github or gitlab), run the command ssh-keygen
in a terminal on your host machine and accept the default values. Once done, (or if you already have SSH-keys):
On linux or MacOS, run ssh-copy-id username@ip-address
to copy your keys to the VM.
On Windows, run type $env:USERPROFILE\.ssh\id_rsa.pub | ssh username@ip-address "cat >> .ssh/authorized_keys"
You may be prompted for your VM password one final time. Enter it, and the command should finish.
Now, try logging in with ssh username@ip-address
to make sure you are no longer being
prompted for your password.
Make the VM headless. If you only ever plan on using your VM via SSH,
you can lighten the load on your computer and increase the speed at which the VM runs
by disabling graphical output.
The exact process for this will vary depending on
which hypervisor you're using, but after turning the VM off with sudo poweroff
,
the idea is to look through the VM settings for some kind of "graphical output" checkbox.
Easy whitespace spotting. If you are a vim
user,
you can save yourself some substantial hassle chasing down whitespace errors
by adding the following lines to your ~/.vimrc
file:
:highlight ExtraWhitespace ctermbg=red guibg=red
:match ExtraWhitespace /\s\+$/
msg = (silence)
whoami = None
singularity v0.6-4-gbe148cb https://github.com/underground-software/singularity