HOWTO Plan, setup and run a high school Gentoo Club

From Gentoo Linux Wiki

[edit] Introduction

This article is based on my experiences in setting up and running a Gentoo linux club for the pupils at the secondary school where I teach. We have a group of 7 pupils aged 12-15 years and we meet on an almost daily basis.

After a brief discussion on the Gentoo Forums, I decided that I would like to encourage others to set up similar clubs - and that we might all gather our thoughts and useful resources here. Man pages and HOWTOs are great for a lot of folk, but not really suited to a teaching environment. What I would like to develop and share are things like exercises, worksheets and suggested course synopses, all based around Gentoo. So, anyway, here's how we've got on so far, three months after inception

[edit] The Basics

[edit] Aims

1. Build our own network of Gentoo hosts
2. Have Fun with Gentoo- this goes without saying, right?
3. Promote Gentoo in particular and GNU/linux in general.
4. Equip pupils with useful linux based skills, which is certainly not a part of standard secondary curricula.

[edit] Target Group

This comprises about 7 pupils in the age range 12-15. They have no prior linux experience, most come with good working knowledge of Microsoft Windows and/or Apple Mac. Interest and enthusiasm levels are high - these are motivated young people who come of their own free will in their own time.

[edit] Resources

• A teacher / older pupil with some Gentoo installs under their belt
• Piles of old Pentium 2 or better systems that people don't want anymore - many pupils have brought in their own hardware.
• A network switch (ideally at least 16 port just in case you get into clustering). So far this is the only thing we've actually had to buy.
• Some Cat5e network patch cable.
• Access to the internet, at least via an http_proxy.
• A (headless) box to set up as a local rsync and distfiles server.

[edit] Practicalities

• We set up in an area where there is plenty of power trunking and a good bit of space. Equipment can be left without much fear of interference
• The school's IT policy needs to be read over and pupils reminded of their Acceptable Use Agreements.
• The school's internet access is severely restricted, in fact only http and https protocols are possible through a proxy server.
  • The headless box 'steggies' runs rsyncd - that is it provides a local emerge sync mirror for all other hosts to sync against.
  • steggies itself has to sync via emerge-webrsync
  • steggies also provides /usr/portage/distfiles via NFS to cut pressure on gentoo mirrors.

[edit] Starting Up

Before any young people arrived with their ex-windows boxes, I made sure that I had 'steggies' up and running as outlined above as well as having some demonstration systems ready.

These demo machines comprised of a Dell Pentium 2, 300MHz laptop with gdm, fluxbox, firefox and mozilla, and 200MHz box with an old version of SuSE. It would really be worth trying to get a better demo set up than this if you can, but you definitely need something that shows 'This is roughly where we are heading'

Now this brings us to an important point. Are your new users going to do their own installs or are you going to do it for them? I'm not going to labour the point here, but state that my pupils did their own installs, from stage3. It took around 7 weeks with 30 minutes a day, 5 days a week. (Rural school means harder to do after school stuff).

I don't think that you should install systems for them, since then there is no ownership or knowledge at all. However with hindsight I do wish that I had done a 'watch and copy', by installing in front of the pupils and getting them to copy and discuss each step. We have a LCD projector available too, so really I have no excuse!

One final piece of advice - make sure that you have up-to-date copies of the install docs if you are working off paper copies! Gentoo changes and you'll save yourself lots of needless hassle if you use current documentation. I hope that advisory isn't patronising - I admit that I've only written this paragraph after being caught out with devfs in a few kernels here and there.

[edit] Choose Your 'Software Philosophy'

Gentoo is about choice and I emphasise this with the pupils. With the Club members all being novice, I have dictated what packages and display manager we will all use. This is solely to ease the job of creating resources and teaching the basics. I try to point out alternatives that pupils might want to try out later.

The 'philosophy' then - 2.6 gentoo-sources, UDEV and GRUB for booting, reiserfs for root filesystem, syslog-ng, no KDE, no GNOME, yes to GTK and GTK2, fluxbox (with ROX), GDM graphical login, mozilla-firefox, openoffice, nano editor for config files (I intend to introduce emacs later)

[edit] The First Sessions

Crucial for whetting the appetite. This seemed to do the job anyway

[edit] Hardware Inspection

To properly understand how a computer works, we must crack open those cases and take a look at what's inside!

For our purposes, we're going to open up the case so we will know what's what and also to check that we have the minimum hardware we'll need to bring your computer into our gentoo network.

1. Unscrew the screws holding the case together and gently pull the cover off. Newer cases are nicer than these and have tabs that you can pull or hinged doors for easy access. We are not so fortunate to have new cases, so let's pry it open and take a look.
2. Now that you can see the parts inside the computer, see if you guess what some of the parts do. Which component would you call the modem, which uses telephone lines to connect to networks? Look at the back of the CD drive and notice the wide ribbon cable behind it. What other parts connect to this ribbon cable? How many ribbon cables do you see?
3. Having explored some computer hardware, let's get down to business and talk about what does what.
   • Identify the motherboard. This is the large circuit board everything connects to, and provides all the circuitry needed for the individual components to talk to one another.
   • On the motherboard, identify the Central Processing Unit, or CPU for short. This is the "brain" of the computer where control of the circuits is ultimately enforced. Remember that a computer does not think; all a computer can do is turn something on or off.
   • Near the CPU you will see a large chip which probably has a label on it. This is call the North Bridge. The North Bridge serves as an interface between the CPU and the rest of the motherboards' circuits. Remember, computers are built in layers of abstraction. Here we are seeing a layer of abstraction from the peripherals and the CPU. The CPU is used directly by the operating system and eventually software applications, but these software applications exist through several layers of abstraction through human-readable code down to machine code, machine code down to binary digits, binary digits down to electrical signals in the CPU, electrical signals in the CPU out to the other parts of the computer. We'll talk more computer science later, for now lets:
   • Find the South Bridge, which is another large chip on the motherboard but further away the CPU. If you're having trouble finding it, look for the ribbon cable that connects the CD drive to the motherboard. See the port it plugs into? The South Bridge should be somewhere closeby. Why is it close to the IDE port (where the ribbon cable connected to the motherboard)? Because the South Bridge works with the IDE drives!
   • While we're thinking about IDE drives, you should see that the CD drives plug into the same cables as the hard drives. All of them talk to the computer the same way, but hard drives and CD drives are very different!
   • For one thing, CDs are removeable media, which means that you put in and take out CDs whenever you want. Hard drives stay put. You will also see, later, that the storage capacity of hard drives is much larger than that of CD drives. You will also use a command called "hdparm" to see how hard drives are much faster than CD drives! We are going to be installing our operating systems on the hard drives. However, realise that when we install Gentoo we won't be booting from the hard drive, we'll be booting from a CD drive. It is also possible to boot from a floppy or the network, among other things!
   • Back to the motherboard, look for where you plug your monitor into computer. You will see that a blue, 25-pin VGA connector connects the monitor either directly to the motherboard or to a Video Card.
   • Let's look at the Video Card if you have one. Notice the type of slot that it has. What color is the slot? If there's more than one slot just like it and it's colored white then this is a PCI slot. If it's the only slot of it's type and has a chocolate color then it's an AGP slot. Until the advent of a new technology called PCI Express in the past year or so, Video Cards have almost exclusively used AGP to transfer lots of information from the computer to the screen. You may not think that a Video Card has that hard a job until you start playing games. Modern Video Cards can push enourmous amounts of data through the AGP slot every second - in fact most Video Cards even have their own processing unit (the GPU, or Graphical Processing Unit) and memory on them!
   • Speaking of memory, we never looked for that on the motherboard. You will see on the motherboard one or more long sticks of memory, or RAM (Random Access Memory) sticks. Just from looking at them, can you tell how much memory it holds (hint, look for a sticker. If there's no sticker, the answer is usually "no"). How much memory does this computer have total? Is this enough to run Linux?
   • Let's look at the other cards in this computer. Your computer may or may not have a: network card, sound card, modem, or other kinds of cards. What kinds of things plug into what card? Compare and contrast these cards to one another.
   • Finally, let's take a look at the power supply, or PSU. Look at the back of it first. Does your power supply have a fan in it? Do you see a little switch that says "120V", "240V" or something similar (if you move this switch make sure you move it back to 120V or 240V!)? Different countries have a different mains voltage, so if you move this switch you will bork your box. Is there an on/off switch? Looking at this, you will see that the "O" with a bar through the top is used a lot in electronics. Where do you think this symbol came from? Also take note of all the different types of wires coming out of the power supply on the inside of the computer.
4. Now that you're familiar with this hardware, completely disassemble the computer and then put it back together. (The only caveat here is in breaking the thermal contact between the CPU and the cooling fan or heatsink. You will need proper thermal contact paste to restore the contact and inadequate thermal contact will be the end of the CPU. I suggest if you want to totally disassemble then get a 486 and fling the thing in the bin when you are finished.) This should be fun! You may want to take notes if anything was in a certain way (especially those little wires connecting the case to the motherboard - take careful note of what went where). When you've got it back together, see if it boots. If anything seems wrong, think about what it's doing and see if you can figure out what you did wrong. Be very careful when you do this, as some parts inside a computer are sharp and others can be damaged by static electricity or trying to put them in the wrong direction. "Use an electrostatic discharge wrist-strap". It is very important that you ask questions if you think you might break something. Take your time and be patient; the computer worked when you got it so it'll work again when you put it back together correctly. Good luck!
5. Summary - The hardware checks we'll need for our Club purposes are:

• The hard disk is connected to the first IDE slot and is correctly jumpered to be a master or a slave. Misconfiguration will likely cause boot fail / kernel panic.
• The primary (or sole) hard disk will be the one you will eventually boot off of and it should be on the end plug of the first IDE ribbon cable. Any slave HD should be on the middle plug. Misconfiguration will likely cause boot fail / kernel panic.
• The CDROMs and/or DVD players are all on the second IDE slot's ribbon cable, correctly jumpered and positioned. Misconfiguration will likely cause boot fail / kernel panic.
• You have a 10/100 network interface card inserted in a PCI slot.
• You have inserted as much compatible RAM as possible, having hacked the modules out of any donated computers which are really beyond use.
• Remove any winmodems and crunch them firmly under the heel of your boot (ideally this should be a heavy winter walking boot)
• For the most part I remove floppy drive units from cases - there really is no point in keeping these things in there and it is a waste of good case screws.

[edit] First Look at Installed Gentoo System

The rationale in this section is to keep this whole project concrete in the minds of the pupils taking part - we are looking at and working on a fully installed and operational Gentoo host. We have user login, nice graphics to play with and everything is safe warm and fuzzy.

Remembering our ‘software philosophy’, we have one or two volunteers login via GDM, into fluxbox, run an app like openoffice or blobwars, logout, reboot etc.

Now we are looking for some fairly formal exposition on some key topics that pupils need to get a grip on, preferably with handouts (which would be nice to make available here) and a wee quiz to round things off. Our topics are as follows:

[edit] Entering Commands - some BASH

The main things we want to cover here are: (develop an exercise sheet)

1. What is BASH? - Compare it with what may already be familiar - DOS command line. Or just start with a comparison of command driven versus menu driven systems.
2. Getting to a BASH prompt (aterm, xterm) - since for this HOWTO we focus on fluxbox / ROX, our exercises show how to do this, but we also want to show how to use a virtual terminal (CTRL-ALT-F1 etc)
3. Entering Simple Commands like ls,who,pwd,whoami,... - Add to the list but make sure that what the command does is simple and pupils will be able to see what the command does immediately and transparently. The exercise sheet could lead through a sequence of commands and invite pupils to record what they think it is doing.

I think that file and directory commands should not be introduced at this stage, but later in a dedicated session, with ROX graphical file manager to give the pupils some insight into what cd, cp, mv, rm etc are doing. Ideally a suitable exercise would have pupils navigate a directory tree, create copy, move and delete some files, inspect and change permissions. Doing each part of the exercise with ROX and then with BASH (or vice-versa??) generally helps pupils who have previously had to use only a Microsoft based “operating system”

[edit] What is a Kernel?

The kernel of your computers is a program that tells the central processing unit what to do and interprets messages coming from the central processing unit. The kernel is, essentially, an interface between hardware and software.

You can find out which kernel you are using by typing uname -a. On my computer, this returns:

Linux gentoobox 2.6.11-gentoo-r6 #5 SMP Fri Apr 29 01:15:18 GMT 2005 i686 Unknown CPU Typ AuthenticAMD GNU/Linux

This reads: the kernel is a Linux kernel, the name of my computer is "gentoobox", the kernel version is 2.6.11-gentoo-r6, and then there is more information about my specific computer system. Your computer will almost certainly be using Linux 2.4 or 2.6 kernel.

Remember, don't think of a computer in the dualistic sense of hardware and software with a kernel running in between! The software is simply electrical signals running through well-designed circuits.

This diagram (http://www.freeos.com/guides/lsst/ch01sec06.html <-- someone look at this website and see what license the image is copyrighted under; if we can't duplicate it, make a new one or find another). What you as a user sees is both the shell (remember, your shell is Bash) and applications (i.e. ROX is an application). These applications send messages to the shell interpretter. The shell then translates that command into something it can tell the kernel to do. The kernel then processes that request and acts accordingly.

For example, say you want to learn what your IP address is using the "ifconfig" command. You type the command ifconfig into your Bash terminal. Bash will then send a message to the kernel asking for information that ifconfig needs. The kernel will decide whether your user account has the privileges to use that command. If it decides you can use that command, it will return the IP address the kernel is using to talk to the network. The shell will interpret the kernel's answer and format that in human-readable output at your command prompt. If the kernel returns a message to the shell saying you cannot use the ifconfig command the shell will tell you so.

The ifconfig command can also be used to find the MAC, or hardware, address of your network card(s). This time the kernel has to probe the hardware for it's MAC address and will return a number, this number is then interpreted by the shell, which eventually sends a number back to the ifconfig command which prints out the MAC address for the user.

A good talk would be to discuss the growing complaints that the Linux kernel is "too large" and contains "too many features," and compare and contrast the Linux kernel to the BSD-Unix kernels.

[edit] What is my Kernel Version?

As discussed above, get your pupils to type in

uname -a

Talk about the output and compare the results that different pupils have obtained on their respective hardware.

[edit] Gentoo File Hierarchy

In plain English, all that this section aims to cover what parts of GNU/Linux operating system are kept where. Much of this summary is taken from Filesystem Hierarchy Standard

The root of the filesystem is the highest level, under which all other filesystems available to the kernel will be mounted. Under some operating systems this is akin to 'My Computer' or 'C:\'.

We need to develop some simple exercises to aid pupils exploration of this

Try

ls /usr/portage

and have a look at the different categories of software! Pick one of the categories and try

ls /usr/portage/sci-biology

[edit] Simple Hard Disk Partitioning

This is possibly a redundant section, unless for a discussion of putting /boot on /dev/hda1 and not having /boot mounted during normal system operation. Could just put that in the later section on partitioning

[edit] Gentoo Boot Process - dmesg

After booting your machine with the liveCD an interesting and useful thing to have a look at is all the output that goes flying past during boot.

dmesg|less

You'll need to explain the pipe | symbol and how it routes the output of the dmesg command into the less pager. If the keymap has been chosen incorrectly, then you might have a bit of fun finding the pipe symbol on the keyboard. Try SHIFT plus: the bottom left or the top left or just to the left of the enter key.

Using dmesg like this will provide a lot of the basic system info you'll need and encourage pupils to try to identify and record things like: processor clock speed and type, physical RAM, mouse type, presence of hard disks and CD or DVD drives, ethernet driver.

[edit] Mounting - How to Integrate a Filesystem

Do a couple of manual mounts of usb mass storage device, remount part of a filesystem, do an NFS mount, look at /etc/fstab.

[edit] Gentoo Service Start/Stop Mechanism

As an exercise, let's make Gentoo run as an FTP server. For this exercise, we will simply install VSFTPD and configure it for anonymous, read-only access. FTP (File Transfer Protocol) is an old but reliable protocol which is used for moving large individual files through networks quickly.

Step 1: Install VSFTPD
Log in as root and type this command:

emerge vsftpd

Step 2: Configuration
That was easy. Now edit /etc/vsftpd/vsftpd.conf using your favorite text editor and copy this into there:

# See http://wjholden.com/vsftpd-help.html for more on VSFTPD configurations
anonymous_enable=YES
local_enable=NO
write_enable=NO
anon_upload_enable=NO
anon_mkdir_write_enable=NO
dirmessage_enable=YES
chown_uploads=NO
xferlog_enable=YES
idle_session_timeout=600
data_connection_timeout=120
ascii_upload_enable=NO
ascii_download_enable=NO
ftpd_banner=(Put your name here)
chroot_list_enable=YES
background=YES
listen=YES
ls_recurse_enable=NO

Step 3: Starting the daemon
Gentoo provides a centralized place for what are called init scripts. They are stored in /etc/init.d/ and have names representative of the service they start. Init scripts are used to control services you run. To start the VSFTPD server, type:

/etc/init.d/vsftpd start

You can learn more about what you can do with these init scripts by just typing "/etc/init.d/vsftpd" without any arguements ("start" is an arguement, so is "stop", and "restart").

Step 4: Init script configuration
You don't want to type /etc/init.d/vsftpd start every time to turn your computer on, do you? Gentoo provides an easy way to control which init scripts are run when you boot your computer up. To set VSFTPD to start on every boot, type:

rc-update add vsftpd default

As per usual, you can learn more about rc-update by typing "man rc-update".

Oh, and you might want to copy a file into /home/ftp/ to let classmates download. Something you could do to help everyone install things faster would be to spread around the contents of /usr/portage/distfiles/. You can copy those over by typing:

cp /usr/portage/distfiles/* /home/ftp/

Experiment with what happens when you type /etc/init.d/<service> <args> and rc-update <change> <service> <priority> commands. Also find what the hostname or IP address of your friends' computers are and use the "ftp" command to download files from their computers. What happens when you try to upload a file? Can you think of why that is? Can you change it? You may want to emerge gftp for a graphical FTP client.

[edit] Concept of Runlevel in Gentoo

Here we want to explain about system shutdown, boot, default and reboot and probably leave it at that for now. The examples on working with VSFTP elsewhere in this HOWTO will flesh this out a bit.

[edit] Booting our next Box from the LiveCD

Now that the group has seen some of the basic features and principles of a fully installed Gentoo system, it is time to start preparing our next Gentoo host. We pick up here from when you checked over the hard disk jumpering and IDE configuration etc. I recommend that each pupil should have a small notebook. In the back they can note down snippets of hardware info and in the front note down any useful commands they learn.

Get the latest installation LiveCD, one copy for each pupil's system, power up and get the pupils to watch the boot sequence. Expect problems if jumpering is wrong (kernel panics, no boot), or RAM modules are bad (segfaults). If all is well a nice splash image will appear and after a few minutes your pupils will be presented with a command line.

At this stage, demonstrate how to extract key pieces of system information, which the pupils will have to record carefully:

[edit] Get the processor type and available RAM

cat /proc/cpuinfo
cat /proc/meminfo

Pupils can note the cpu flags available - this will be handy when setting up USE flags later. The main things we need are the processor model name and 'MemTotal' physical RAM capacity for setting up swap space later.

[edit] Sound and Graphics Hardware

/sbin/lspci | grep -i audio
/sbin/lspci | grep -i vga

[edit] Network Card

/sbin/lspci | grep -i ethernet

[edit] cfdisk Windows

The hard disks of most donated or brought in computers have endured Microsoft Windows installations and NTFS or DOS formatted partitions. It is time to liberate these disks, not only by reformatting them (next section) but first by re-partitioning them. For the purposes of our Club, we will not be entertaining dual boot systems (at least not at this stage), so we will be wiping all partition information and after this stage any data on the disk will be lost (except to painful and time-consuming recovery software).

The install docs speak of using the fdisk program, however I find pupils have more success with cfdisk.

cfdisk /dev/hda

The standard Club partitioning layout will be (ext2/reiserfs will be set up next):

The main features we need for the Club are that hda1 is big enough for lots of kernels for messing around, hda2 is about double the physical RAM, although why anyone would need more that 1Gb of swap I can't see, hda3 is just the rest of the disk.

From the pupils point of view, before they tackle the cfdisk, we need to explain that they are partitioning the hard disk (they will still need to format the partitions), that hda1 will be used to store what is needed to boot the system without the boot disc, that swap (hda2) is just like virtual memory in windows, that in a production server you would not just dump hda3 as the unpartitioned root of the filesystem, but we will in this Club, just to keep it simple. Other teaching points concern primary,logical and extended partitions and of course the need to actually write the table to disk! To be honest, so far I have avoided discussion of primary, logical and extended partitions.

[edit] Formatting partitions

For Club purposes, the suggested layout assumed here is

mke2fs /dev/hda1 (for /boot)
mkswap /dev/hda2 (for swap)
mkreiserfs /dev/hda3 (for /)

There are a number of available file systems for Linux. Traditionally, ext2 [1] was the most common. In terms of performance, ext2 does well for a moderate number of relatively large files but wastes space for numerous small files.

Ext2 has now been largely replaced by the journaling file system ext3 [2]. An offshoot of ext2, ext3 provides journaling. In the journaling process, as files are written to disk information about those changes is also written to a journal in a specific order. Should the disk cease writing (for example due to a power loss) before completely storing the file and all associated information about that file, information in the journal can be used to bring the file system back to a consistent state.

ReiserFS is another file system employing journaling. It has the advantages of being both fast and efficient for use of storage by relying on a B-TREE structure to represent data on the disk. ReiserFS is arguably a best of both worlds file system. However, it's relatively recent introduction compared to ext2 and ext3 means a lack of thorough vendor support for utilities, quotas, and file recovery.

For very large file systems, users may want to consider XFS originally designed by Silicon Graphics. Unlike ext2 or ext3, XFS stores information about where files are stored in several different places on the disk. This means fewer rotations of the drive to look up the physical locations where pieces of a file are actually stored. XFS is built for speed but may not be particularly efficient in terms of disk usage. XFS does provide journaling. Vendors recommend occasional maintenance to keep it running smoothly.

[edit] LiveCD environment -vs- Installed System

They are not the same thing. Right now, you are booted off the CD. We want to be able to boot of the hard disk - once that works we have an installed base system

The Club now continues with the installation of the base system We don't need to re-write that doc here but over time we need to add sections with the main teaching points and accompanying exercises.

[edit] Beginner Projects

Now that your group has been through a Gentoo install and has covered some of the basics, now might be a good time to pursue some of the pupils interests more strongly.

1. Apache Webserver - running on your Gentoo club network. Once a basic setup is completed, can look at some elementary HTML editing. We've already got an FTP server set up from earlier, so the process of setting up server software should feel natural now.
2. GIMP - get some graphics on the go. Create icons reflecting the pupils choices of hostnames and use these images on the logon screen.
3. grip - introduce the ogg/mp3 ripping of CDs. (Wouldn't it be nice to have OpenMosix for this? - Maybe later.)
4. MPlayer - especially if there is a DVD player or fast enough internet connection
5. Burning CDs
6. Mounting a usb mass storage device. Use ROX to mount/unmount from the desktop
7. Experiment with a range of desktops and window managers
8. Play xpilots over a network, learning about the client/server model in the process.

[edit] Advancing Your Club Members' Skills

This section describes ideas aimed at pushing up the skill level of your Gentoo Club's members.

1. HOWTO run a Gentoo Install Competition - The instructor demonstrates a vanilla install from start to finish, competitors work on identical boxes, with points awarded on reaching key stages, bonus points for booting first time and penalties each time the instructor is asked to take the keyboard!