Funtoo Linux - User contributions [en]

Welcome

2013-03-21T08:14:25Z

Palica: Undo revision 8979 by Khezaltulaiz101 (talk)

<div style="float:right; width: 35%">
{{#widget:Donate|blurb=Your support helps Funtoo grow! Donate Today.}}
<div class="boxy">
== Get on the UserMap! ==
{{#compound_query:[[Category:People]] [[Role type::Staff]];?Geoloc;icon=Purplemarker.png
|[[Category:People]][[Role type::Contributor]];?Geoloc;icon=Orangemarker.png
|[[Category:People]][[Role type::User]];?Geoloc;icon=Greenmarker.png
|format=googlemaps3|height=275|zoom=1|type=hybrid|markercluster=yes}}
See our full-size [[Usermap]] and find out how to become part of the Funtoo Universe!
</div>
{{Litecoin|blurb=Check it out: Mine litecoins for Funtoo!}}
<div class="boxy">
=== Latest Commits: ===
<ul>
<feed entries=7 url="https://github.com/funtoo/funtoo-overlay/commits/master.atom">
<li>[{PERMALINK} <nowiki>{TITLE}</nowiki>]
</feed>
</ul>
</div>

<div class="boxy">
=== Featured Resources: ===
<DynamicPageList>
category = Featured
</DynamicPageList>
</div>

<div class="boxy2">
=== [[image:Feed-icon-28x28.png|link=http://forums.funtoo.org/extern.php?action=feed&type=atom]] Latest Forum Posts ===
<ul>
<feed entries=6 url="http://forums.funtoo.org/extern.php?action=feed&type=atom">
<li>[{PERMALINK} <nowiki>{TITLE}</nowiki>]
</feed>
</ul>
</div>

<div class="boxy2">
=== [[image:Feed-icon-28x28.png|link=http://feeds.feedburner.com/planet_larry]] Planet Larry ===
<ul>
<feed type="planet" entries=6 url="http://feeds.feedburner.com/planet_larry">
<li>[{PERMALINK} <nowiki>{TITLE}</nowiki>]
</feed>
</ul>
</div>

</div>

= Welcome to the Funtoo Wiki! =

[[Funtoo Linux]] is a Linux-based operating system created by [[user:Drobbins|Daniel Robbins]], the creator and former Chief Architect of Gentoo Linux.

Funtoo Linux is a Free software, or "Open Source" operating system. All distribution source code is freely available, and it can be used and distributed free of charge.

== Featured Video ==

In this video, Jonathan Vasquez ([[User:Fearedbliss|fearedbliss]]) of the Funtoo Linux Core Team walks you through the process of installing Funtoo Linux with ZFS. See the [[ZFS Install Guide]] for detailed instructions.

{{#widget:YouTube|id=MXyBamArues|width=640|height=360}}

== Meta-Distribution, Optimized ==

Funtoo Linux is also a ''meta''-distribution, which means that it is built automatically from source code and is customized with the functionality that ''you'' want it to have, and ''without'' the unnecessary features and "bloat" that you want to avoid.

In addition, a Funtoo Linux system is [[Download|optimized for your CPU]], and we offer optimized versions for ''Intel Core i7'', ''Intel Atom'', ''AMD Opteron'', and other processors and architectures.

These combination of factors work together to create an extremely high-performance and flexible computing platform -- a platform where ''you'' are in control, and your system performs optimally. We believe that Funtoo Linux is the most ideal expression of how operating system technology "should" work, and we continually strive to make it better.

== The Gentoo Ecosystem ==

Our [[Core Team]] is focused on advancing the state-of-the-art in Linux distributions by developing our own improvements to Gentoo Linux, while remaining compatible with the upstream changes from the Gentoo Linux project.

We are committed to maintaining high-levels of compatibility and collaboration with the Gentoo Linux project, and challenge ourselves to innovate while providing new approaches that can be easily leveraged by the Gentoo Community. We appreciate the support we receive from members of the Gentoo Community and strive to contribute back to the larger [[Gentoo Ecosystem]].

== Ultimate Flexibility for Developers ==

Does your Linux distribution allow multiple versions of <tt>php</tt>, <tt>[[python]]</tt> or <tt>ruby</tt> installed happily alongside each other? Funtoo Linux does. Are you tired of hand-building key packages from source to configure them exactly the way you want? Funtoo Linux allows you to tweak the build-time features of packages using handy things called USE variables. Other distributions are forced to either leave stuff out that you want, or include stuff you don't want.

== Virtualization ==

We support the [[OpenVZ]] project and build up-to-date Funtoo Linux OpenVZ containers that you can [[Download|download]]. Also see [[VagrantUp]] for a nice way to deploy VirtualBox-based Funtoo Linux systems. [[Metro]], our automated distro build tool, is capable of building OpenVZ, Linux VServer and [[Linux Containers]] (LXC) images. Funtoo Linux also makes an excellent virtualization host system for [[Xen]].

== Features ==

[[Funtoo Linux]] features native [[wikipedia:UTF-8|UTF-8]] support enabled by default, a [[wikipedia:Git (software)|git]]-based, [[Portage Tree|distributed Portage Tree]] and funtoo overlay, an enhanced [[Portage]] with more compact mini-manifest tree, automated imports of new [http://www.gentoo.org Gentoo] changes every 12 hours, [[GUID Booting Guide|GPT/GUID boot support]] and [[Boot-Update|streamlined boot configuration]], [[Funtoo Linux Networking|enhanced network configuration]], up-to-date [http://ftp.osuosl.org/pub/funtoo/funtoo-stable/ stable] and [http://ftp.osuosl.org/pub/funtoo/funtoo-current/ current] Funtoo [[Stage Tarball|stages]], all built using Funtoo's [[Metro]] build tool. We also offer Ubuntu Server, Debian, RHEL and Fedora-based [[Funtoo Linux Kernels|kernels]].

Funtoo is currently supported on the following processor families :
* PC-compatible, both 32 and 64-bit (''x86-32bit'', ''x86-64bit'')

== Resources ==

* Learn more about [[Funtoo Linux]].
* Why you should [[Choose Funtoo]]: ...and how its different than other distros.
* Visit [[:Category:Projects|Funtoo Linux Projects]] and also look at the stuff online for [[Metro]].
* Learn [[:Category:Linux Core Concepts| Core Linux concepts]] from articles originally written by Daniel Robbins.

__NOTOC__
__NOTITLE__
__NOEDITSECTION__

[[Category:Funtoo|*]]

Rootfs over encrypted lvm over raid-1 on GPT

2013-03-21T08:13:24Z

Palica: /* Rootfs over encrypted lvm over raid-1 on GPT */

This howto describes how to setup LVM and rootfs with cryptoLUKS-encrypted raid-1 over drive with GPT
= Rootfs over encrypted lvm over raid-1 on GPT =

To start read [[Rootfs_over_encrypted_lvm|Rootfs over encrypted lvm]]

How to prepare the hard disk for GPT read [[Funtoo_Linux_Installation#GPT_Partitions|Funtoo Linux Installation on GPT_Partitions]].
For example, installing a new system on /dev/sdb Be careful ;) I warned you!

<pre>[root@localhost ~]# gdisk -l /dev/sdb
GPT fdisk (gdisk) version 0.6.13

Partition table scan:
MBR: protective
BSD: not present
APM: not present
GPT: present

Found valid GPT with protective MBR; using GPT.
Disk /dev/sdb: 625142448 sectors, 298.1 GiB
Logical sector size: 512 bytes
Disk identifier (GUID): 67AC0F92-E033-4B53-B6C5-D99DD8F49D90
Partition table holds up to 128 entries
First usable sector is 34, last usable sector is 625142414
Partitions will be aligned on 2048-sector boundaries
Total free space is 3038 sectors (1.5 MiB)

Number Start (sector) End (sector) Size Code Name
1 2048 206847 100.0 MiB 0700 Linux/Windows data
2 206848 207871 512.0 KiB EF02 BIOS boot partition
3 208896 625142414 298.0 GiB FD00 Linux RAID
</pre>

If you plan to use a raid-1 for installing only one partition (/dev/sdb3 in example) and, if successful, later add more to the mirror, issue something like:

<pre>mdadm --create /dev/md0 --level=1 --raid-devices=2 missing /dev/sdb3</pre>

If you prefer to add the two final destination devices to the array in the first place, issue something like:

<pre>mdadm --create /dev/md0 --level=1 --raid-devices=2 /dev/sda3 /dev/sdb3</pre>

If everything worked well, the arrays will start synchronising immediately. You can monitor this progress by viewing at the content of /proc/mdstat :

<pre>root@golf576:~# cat /proc/mdstat
Personalities : [raid1] [raid0] [raid6] [raid5] [raid4]
md2 : active raid1 sdb5[1] sda5[0]
581595328 blocks [2/2] [UU]
resync=DELAYED

md1 : active raid1 sdb4[1] sda4[0]
41942976 blocks [2/2] [UU]
[>....................] resync = 1.6% (691456/41942976) finish=8.9min speed=76828K/sec

md0 : active raid1 sdb1[1] sda1[0]
511936 blocks [2/2] [UU]

unused devices: <none>
root@golf576:~#</pre>

Now, that's awesome, isn't it? :)
Even more awesome is the fact that you can immediately start using your shiny new RAID. It will finish it's sync in the background while you do changes to it's filesystem.

= Encrypting the raid-1 =

<pre>cryptsetup -c aes-xts-plain luksFormat /dev/md0
cryptsetup luksOpen /dev/md0 dmcrypt_root</pre>

Further, all the same [http://docs.funtoo.org/Rootfs_over_encrypted_lvm as here]… The differences begin with the "Initramfs setup and configuration"

To activate the raid-1 during boot to perform:
<pre>echo "Activating RAID device."
if [ ! -e '/etc/mdadm.conf' ]
then
echo "DEVICE /dev/sda[0-9] /dev/sdb[0-9] /dev/md[0-9]" > /etc/mdadm.conf
mdadm --examine --scan --config=/etc/mdadm.conf >> /etc/mdadm.conf
mdadm --assemble --scan
fi</pre>

Or use [https://github.com/slashbeast/better-initramfs better-initramfs with raid-1 mdadm support]
<pre>git clone https://github.com/slashbeast/better-initramfs.git</pre>
This script is well documented at it's GitHub overview site (which displays the documentation from README.rst).

= Grub2 configuration =
Importantly do not forget <pre>enc_root=/dev/md0</pre>

= Additional links =
* [http://en.gentoo-wiki.com/wiki/RAID/Software RAID/Software]
* [http://www.gentoo.org/doc/en/gentoo-x86+raid+lvm2-quickinstall.xml Gentoo Linux x86 with Software Raid and LVM2 Quick Install Guide]

[[Category:HOWTO]]

Linux Fundamentals, Part 1

2013-03-21T08:02:45Z

Palica: Undo revision 8974 by 117.218.53.13 (talk)

== Before You Start ==

=== About this tutorial ===
Welcome to "Linux fundamentals," the first of four tutorials designed to prepare you for the Linux Professional Institute's 101 exam. In this tutorial, we'll introduce you to bash (the standard Linux shell), show you how to take full advantage of standard Linux commands like ls, cp, and mv, explain inodes and hard and symbolic links, and much more. By the end of this tutorial, you'll have a solid grounding in Linux fundamentals and will even be ready to begin learning some basic Linux system administration tasks. By the end of this series of tutorials (eight in all), you'll have the knowledge you need to become a Linux Systems Administrator and will be ready to attain an LPIC Level 1 certification from the Linux Professional Institute if you so choose.

This particular tutorial (Part 1) is ideal for those who are new to Linux, or those who want to review or improve their understanding of fundamental Linux concepts like copying and moving files, creating symbolic and hard links, and using Linux' standard text-processing commands along with pipelines and redirection. Along the way, we'll share plenty of hints, tips, and tricks to keep the tutorial meaty and practical, even for those with a good amount of previous Linux experience. For beginners, much of this material will be new, but more experienced Linux users may find this tutorial to be a great way of rounding out their fundamental Linux skills.

For those who have taken the release 1 version of this tutorial for reasons other than LPI exam preparation, you probably don't need to take this one. However, if you do plan to take the exams, you should strongly consider reading this revised tutorial.

== Introducing bash ==
=== The shell ===
If you've used a Linux system, you know that when you log in, you are greeted by a prompt that looks something like this:
<pre>
$
</pre>
The particular prompt that you see may look quite different. It may contain your systems host name, the name of the current working directory, or both. But regardless of what your prompt looks like, there's one thing that's certain. The program that printed that prompt is called a "shell," and it's very likely that your particular shell is a program called bash.

=== Are you running bash? ===
You can check to see if you're running bash by typing:
<pre>
$ echo $SHELL
/bin/bash
</pre>
If the above line gave you an error or didn't respond similarly to our example, then you may be running a shell other than bash. In that case, most of this tutorial should still apply, but it would be advantageous for you to switch to bash for the sake of preparing for the 101 exam.

=== About bash ===
Bash, an acronym for "Bourne-again shell," is the default shell on most Linux systems. The shell's job is to obey your commands so that you can interact with your Linux system. When you're finished entering commands, you may instruct the shell to exit or logout, at which point you'll be returned to a login prompt.

By the way, you can also log out by pressing control-D at the bash prompt.

=== Using "cd" ===
As you've probably found, staring at your bash prompt isn't the most exciting thing in the world. So, let's start using bash to navigate around our file system. At the prompt, type the following (without the $):
<pre>
$ cd /
</pre>
We've just told bash that you want to work in /, also known as the root directory; all the directories on the system form a tree, and / is considered the top of this tree, or the root. cd sets the directory where you are currently working, also known as the "current working directory."

=== Paths ===
To see bash's current working directory, you can type:
<pre>
$ pwd
/
</pre>
In the above example, the / argument to cd is called a ''path''. It tells cd where we want to go. In particular, the / argument is an ''absolute'' path, meaning that it specifies a location relative to the root of the file system tree.

=== Absolute paths ===
Here are some other absolute paths:
<pre>
/dev
/usr
/usr/bin
/usr/local/bin
</pre>
As you can see, the one thing that all absolute paths have in common is that they begin with /. With a path of /usr/local/bin, we're telling cd to enter the / directory, then the usr directory under that, and then local and bin. Absolute paths are always evaluated by starting at / first.

=== Relative paths ===
The other kind of path is called a ''relative path''. Bash, cd, and other commands always interpret these paths relative to the current directory. Relative paths never begin with a /. So, if we're in /usr:
<pre>
$ cd /usr
</pre>
Then, we can use a relative path to change to the /usr/local/bin directory:
<pre>
$ cd local/bin
$ pwd
/usr/local/bin
</pre>

=== Using .. ===
Relative paths may also contain one or more .. directories. The .. directory is a special directory that points to the parent directory. So, continuing from the example above:
<pre>
$ pwd
/usr/local/bin
$ cd ..
$ pwd
/usr/local
</pre>
As you can see, our current directory is now /usr/local. We were able to go "backwards" one directory, relative to the current directory that we were in.

In addition, we can also add .. to an existing relative path, allowing us to go into a directory that's alongside one we are already in, for example:
<pre>
$ pwd
/usr/local
$ cd ../share
$ pwd
/usr/share
</pre>

=== Relative path examples ===
Relative paths can get quite complex. Here are a few examples, all without the resultant target directory displayed. Try to figure out where you'll end up after typing these commands:
<pre>
$ cd /bin
$ cd ../usr/share/zoneinfo

$ cd /usr/X11R6/bin
$ cd ../lib/X11

$ cd /usr/bin
$ cd ../bin/../bin
</pre>
Now, try them out and see if you got them right :)

=== Understanding "." ===
Before we finish our coverage of cd, there are a few more things I need to mention. First, there is another special directory called ., which means "the current directory". While this directory isn't used with the cd command, it's often used to execute some program in the current directory, as follows:
<pre>
$ ./myprog
</pre>
In the above example, the myprog executable residing in the current working directory will be executed.

=== cd and the home directory ===
If we wanted to change to our home directory, we could type:
<pre>
$ cd
</pre>
With no arguments, cd will change to your home directory, which is /root for the superuser and typically /home/username for a regular user. But what if we want to specify a file in our home directory? Maybe we want to pass a file argument to the myprog command. If the file lives in our home directory, we can type:
<pre>
$ ./myprog /home/drobbins/myfile.txt
</pre>
However, using an absolute path like that isn't always convenient. Thankfully, we can use the ~ (tilde) character to do the same thing:
<pre>
$ ./myprog ~/myfile.txt
</pre>

=== Other users' home directories ===
Bash will expand a lone ~ to point to your home directory, but you can also use it to point to other users' home directories. For example, if we wanted to refer to a file called fredsfile.txt in Fred's home directory, we could type:
<pre>
$ ./myprog ~fred/fredsfile.txt
</pre>

== Using Linux Commands ==

=== Introducing ls ===
Now, we'll take a quick look at the ls command. Very likely, you're already familiar with ls and know that typing it by itself will list the contents of the current working directory:
<pre>
$ cd /usr
$ ls
X11R6 doc i686-pc-linux-gnu lib man sbin ssl
bin gentoo-x86 include libexec portage share tmp
distfiles i686-linux info local portage.old src
</pre>
By specifying the -a option, you can see all of the files in a directory, including hidden files: those that begin with .. As you can see in the following example, ls -a reveals the . and .. special directory links:
<pre>
$ ls -a
. bin gentoo-x86 include libexec portage share tmp
.. distfiles i686-linux info local portage.old src
X11R6 doc i686-pc-linux-gnu lib man sbin ssl
</pre>

=== Long directory listings ===
You can also specify one or more files or directories on the ls command line. If you specify a file, ls will show that file only. If you specify a directory, ls will show the ''contents'' of the directory. The -l option comes in very handy when you need to view permissions, ownership, modification time, and size information in your directory listing.

In the following example, we use the -l option to display a full listing of my /usr directory.
<pre>
$ ls -l /usr
drwxr-xr-x 7 root root 168 Nov 24 14:02 X11R6
drwxr-xr-x 2 root root 14576 Dec 27 08:56 bin
drwxr-xr-x 2 root root 8856 Dec 26 12:47 distfiles
lrwxrwxrwx 1 root root 9 Dec 22 20:57 doc -> share/doc
drwxr-xr-x 62 root root 1856 Dec 27 15:54 gentoo-x86
drwxr-xr-x 4 root root 152 Dec 12 23:10 i686-linux
drwxr-xr-x 4 root root 96 Nov 24 13:17 i686-pc-linux-gnu
drwxr-xr-x 54 root root 5992 Dec 24 22:30 include
lrwxrwxrwx 1 root root 10 Dec 22 20:57 info -> share/info
drwxr-xr-x 28 root root 13552 Dec 26 00:31 lib
drwxr-xr-x 3 root root 72 Nov 25 00:34 libexec
drwxr-xr-x 8 root root 240 Dec 22 20:57 local
lrwxrwxrwx 1 root root 9 Dec 22 20:57 man -> share/man
lrwxrwxrwx 1 root root 11 Dec 8 07:59 portage -> gentoo-x86/
drwxr-xr-x 60 root root 1864 Dec 8 07:55 portage.old
drwxr-xr-x 3 root root 3096 Dec 22 20:57 sbin
drwxr-xr-x 46 root root 1144 Dec 24 15:32 share
drwxr-xr-x 8 root root 328 Dec 26 00:07 src
drwxr-xr-x 6 root root 176 Nov 24 14:25 ssl
lrwxrwxrwx 1 root root 10 Dec 22 20:57 tmp -> ../var/tmp
</pre>
The first column displays permissions information for each item in the listing. I'll explain how to interpret this information in a bit. The next column lists the number of links to each file system object, which we'll gloss over now but return to later. The third and fourth columns list the owner and group, respectively. The fifth column lists the object size. The sixth column is the "last modified" time or "mtime" of the object. The last column is the object's name. If the file is a symbolic link, you'll see a trailing -> and the path to which the symbolic link points.

=== Looking at directories ===
Sometimes, you'll want to look at a directory, rather than inside it. For these situations, you can specify the -d option, which will tell ls to look at any directories that it would normally look inside:
<pre>
$ ls -dl /usr /usr/bin /usr/X11R6/bin ../share
drwxr-xr-x 4 root root 96 Dec 18 18:17 ../share
drwxr-xr-x 17 root root 576 Dec 24 09:03 /usr
drwxr-xr-x 2 root root 3192 Dec 26 12:52 /usr/X11R6/bin
drwxr-xr-x 2 root root 14576 Dec 27 08:56 /usr/bin
</pre>

=== Recursive and inode listings ===
So you can use -d to look at a directory, but you can also use -R to do the opposite: not just look inside a directory, but recursively look inside all the files and directories inside that directory! We won't include any example output for this option (since it's generally voluminous), but you may want to try a few ls -R and ls -Rl commands to get a feel for how this works.

Finally, the -i ls option can be used to display the inode numbers of the file system objects in the listing:
<pre>
$ ls -i /usr
1409 X11R6 314258 i686-linux 43090 libexec 13394 sbin
1417 bin 1513 i686-pc-linux-gnu 5120 local 13408 share
8316 distfiles 1517 include 776 man 23779 src
43 doc 1386 info 93892 portage 36737 ssl
70744 gentoo-x86 1585 lib 5132 portage.old 784 tmp
</pre>

=== Understanding inodes ===
Every object on a file system is assigned a unique index, called an inode number. This might seem trivial, but understanding inodes is essential to understanding many file system operations. For example, consider the . and .. links that appear in every directory. To fully understand what a .. directory actually is, we'll first take a look at /usr/local's inode number:
<pre>
$ ls -id /usr/local
5120 /usr/local
</pre>
The /usr/local directory has an inode number of 5120. Now, let's take a look at the inode number of /usr/local/bin/..:
<pre>
$ ls -id /usr/local/bin/..
5120 /usr/local/bin/..
</pre>
As you can see, /usr/local/bin/.. has the same inode number as /usr/local! Here's how we can come to grips with this shocking revelation. In the past, we've considered /usr/local to be the directory itself. Now, we discover that inode 5120 is in fact the directory, and we have found two directory entries (called "links") that point to this inode. Both /usr/local and /usr/local/bin/.. are links to inode 5120. Although inode 5120 only exists in one place on disk, multiple things link to it. Inode 5120 is the actual entry on disk.

In fact, we can see the total number of times that inode 5120 is referenced by using the <pre>ls -dl</pre> command:
<pre>
$ ls -dl /usr/local
drwxr-xr-x 8 root root 240 Dec 22 20:57 /usr/local
</pre>
If we take a look at the second column from the left, we see that the directory /usr/local (inode 5120) is referenced eight times. On my system, here are the various paths that reference this inode:
<pre>
/usr/local
/usr/local/.
/usr/local/bin/..
/usr/local/games/..
/usr/local/lib/..
/usr/local/sbin/..
/usr/local/share/..
/usr/local/src/..
</pre>

=== mkdir ===
Let's take a quick look at the mkdir command, which can be used to create new directories. The following example creates three new directories, tic, tac, and toe, all under /tmp:
<pre>
$ cd /tmp
$ mkdir tic tac toe
</pre>
By default, the mkdir command doesn't create parent directories for you; the entire path up to the next-to-last element needs to exist. So, if you want to create the directories '''won/der/ful''', you'd need to issue three separate mkdir commands:
<pre>
$ mkdir won/der/ful
mkdir: cannot create directory `won/der/ful': No such file or directory
$ mkdir won
$ mkdir won/der
$ mkdir won/der/ful
</pre>
However, mkdir has a handy -p option that tells mkdir to create any missing parent directories, as you can see here:
<pre>
$ mkdir -p easy/as/pie
</pre>
All in all, pretty straightforward. To learn more about the mkdir command, type man mkdir to read the manual page. This will work for nearly all commands covered here (for example, man ls), except for cd, which is built-in to bash.

=== touch ===
Now, we're going to take a quick look at the cp and mv commands, used to copy, rename, and move files and directories. To begin this overview, we'll first use the touch command to create a file in /tmp:
<pre>
$ cd /tmp
$ touch copyme
</pre>
The touch command updates the "mtime" of a file if it exists (recall the sixth column in ls -l output). If the file doesn't exist, then a new, empty file will be created. You should now have a '''/tmp/copyme''' file with a size of zero.

=== echo ===
Now that the file exists, let's add some data to the file. We can do this using the echo command, which takes its arguments and prints them to standard output. First, the echo command by itself:
<pre>
$ echo "firstfile"
firstfile
</pre>
Now, the same echo command with output redirection:
<pre>
$ echo "firstfile" > copyme
</pre>
The greater-than sign tells the shell to write echo's output to a file called copyme. This file will be created if it doesn't exist, and will be overwritten if it does exist. By typing ls -l, we can see that the copyme file is 10 bytes long, since it contains the word firstfile and the newline character:
<pre>
$ ls -l copyme
-rw-r--r-- 1 root root 10 Dec 28 14:13 copyme
</pre>

=== cat and cp ===
To display the contents of the file on the terminal, use the cat command:
<pre>
$ cat copyme
firstfile
</pre>
Now, we can use a basic invocation of the cp command to create a copiedme file from the original copyme file:
<pre>
$ cp copyme copiedme
</pre>
Upon investigation, we find that they are truly separate files; their inode numbers are different:
<pre>
$ ls -i copyme copiedme
648284 copiedme 650704 copyme
</pre>

=== mv ===
Now, let's use the mv command to rename "copiedme" to "movedme". The inode number will remain the same; however, the filename that points to the inode will change.
<pre>
$ mv copiedme movedme
$ ls -i movedme
648284 movedme
</pre>
A moved file's inode number will remain the same as long as the destination file resides on the same file system as the source file. We'll take a closer look at file systems in [[Linux Fundamentals, Part 3]] of this tutorial series.

While we're talking about mv, let's look at another way to use this command. mv, in addition to allowing us to rename files, also allows us to move one or more files to another location in the directory hierarchy. For example, to move '''/var/tmp/myfile.txt''' to '''/home/drobbins''' (which happens to be my home directory,) I could type:
<pre>
$ mv /var/tmp/myfile.txt /home/drobbins
</pre>
After typing this command, myfile.txt will be moved to '''/home/drobbins/myfile.txt'''. And if '''/home/drobbins''' is on a different file system than /var/tmp, the mv command will handle the copying of myfile.txt to the new file system and erasing it from the old file system. As you might guess, when myfile.txt is moved between file systems, the myfile.txt at the new location will have a new inode number. This is because every file system has its own independent set of inode numbers.

We can also use the mv command to move multiple files to a single destination directory. For example, to move myfile1.txt and myarticle3.txt to /home/drobbins, I could type:
<pre>
$ mv /var/tmp/myfile1.txt /var/tmp/myarticle3.txt /home/drobbins
</pre>

== Creating Links and Removing Files ==

=== Hard links ===
We've mentioned the term "link" when referring to the relationship between directory entries (the "names" we type) and inodes (the index numbers on the underlying file system that we can usually ignore.) There are actually two kinds of links available on Linux. The kind we've discussed so far are called hard links. A given inode can have any number of hard links, and the inode will persist on the file system until all the hard links disappear. When the last hard link disappears and no program is holding the file open, Linux will delete the file automatically. New hard links can be created using the ln command:
<pre>
$ cd /tmp
$ touch firstlink
$ ln firstlink secondlink
$ ls -i firstlink secondlink
15782 firstlink 15782 secondlink
</pre>
As you can see, hard links work on the inode level to point to a particular file. On Linux systems, hard links have several limitations. For one, you can only make hard links to files, not directories. That's right; even though . and .. are system-created hard links to directories, you (even as the "root" user) aren't allowed to create any of your own. The second limitation of hard links is that they can't span file systems; which would be the case if the file systems are on separate disk partitions. This means that you can't create a link from /usr/bin/bash to /bin/bash if your / and /usr directories exist on separate disk partitions.

=== Symbolic links ===

In practice, symbolic links (or symlinks) are used more often than hard links. Symlinks are a special file type where the link refers to another file by name, rather than directly to the inode. Symlinks do not prevent a file from being deleted; if the target file disappears, then the symlink will just be unusable, or broken.

A symbolic link can be created by passing the -s option to ln.
<pre>
$ ln -s secondlink thirdlink
$ ls -l firstlink secondlink thirdlink
-rw-rw-r-- 2 agriffis agriffis 0 Dec 31 19:08 firstlink
-rw-rw-r-- 2 agriffis agriffis 0 Dec 31 19:08 secondlink
lrwxrwxrwx 1 agriffis agriffis 10 Dec 31 19:39 thirdlink -> secondlink
</pre>
Symbolic links can be distinguished in ls -l output from normal files in three ways. First, notice that the first column contains an l character to signify the symbolic link. Second, the size of the symbolic link is the number of characters in the target (secondlink, in this case). Third, the last column of the output displays the target filename preceded by a cute little ->.

=== Symlinks in-depth ===
Symbolic links are generally more flexible than hard links. You can create a symbolic link to any type of file system object, including directories. And because the implementation of symbolic links is based on paths (not inodes), it's perfectly fine to create a symbolic link that points to an object on another physical file system; that is, a different disk partition. However, this fact can also make symbolic links tricky to understand.

Consider a situation where we want to create a link in /tmp that points to /usr/local/bin. Should we type this:
<pre>
$ ln -s /usr/local/bin bin1
$ ls -l bin1
lrwxrwxrwx 1 root root 14 Jan 1 15:42 bin1 -> /usr/local/bin
</pre>
Or alternatively:
<pre>
$ ln -s ../usr/local/bin bin2
$ ls -l bin2
lrwxrwxrwx 1 root root 16 Jan 1 15:43 bin2 -> ../usr/local/bin
</pre>
As you can see, both symbolic links point to the same directory. However, if our second symbolic link is ever moved to another directory, it will be "broken" because of the relative path:
<pre>
$ ls -l bin2
lrwxrwxrwx 1 root root 16 Jan 1 15:43 bin2 -> ../usr/local/bin
$ mkdir mynewdir
$ mv bin2 mynewdir
$ cd mynewdir
$ cd bin2
bash: cd: bin2: No such file or directory
</pre>
Because the directory /tmp/usr/local/bin doesn't exist, we can no longer change directories into bin2; in other words, bin2 is now broken.

For this reason, it is sometimes a good idea to avoid creating symbolic links with relative path information. However, there are many cases where relative symbolic links come in handy. Consider an example where you want to create an alternate name for a program in /usr/bin:
<pre>
# ls -l /usr/bin/keychain
-rwxr-xr-x 1 root root 10150 Dec 12 20:09 /usr/bin/keychain
</pre>
As the root user, you may want to create an alternate name for "keychain", such as "kc". In this example, we have root access, as evidenced by our bash prompt changing to "#". We need root access because normal users aren't able to create files in /usr/bin. As root, we could create an alternate name for keychain as follows:
<pre>
# cd /usr/bin
# ln -s /usr/bin/keychain kc
# ls -l keychain
-rwxr-xr-x 1 root root 10150 Dec 12 20:09 /usr/bin/keychain
# ls -l kc
lrwxrwxrwx 1 root root 17 Mar 27 17:44 kc -> /usr/bin/keychain
</pre>
In this example, we created a symbolic link called kc that points to the file /usr/bin/keychain.

While this solution will work, it will create problems if we decide that we want to move both files, /usr/bin/keychain and /usr/bin/kc to /usr/local/bin:
<pre>
# mv /usr/bin/keychain /usr/bin/kc /usr/local/bin
# ls -l /usr/local/bin/keychain
-rwxr-xr-x 1 root root 10150 Dec 12 20:09 /usr/local/bin/keychain
# ls -l /usr/local/bin/kc
lrwxrwxrwx 1 root root 17 Mar 27 17:44 kc -> /usr/bin/keychain
</pre>
Because we used an absolute path in our symbolic link, our kc symlink is still pointing to /usr/bin/keychain, which no longer exists since we moved /usr/bin/keychain to /usr/local/bin.

That means that kc is now a broken symlink. Both relative and absolute paths in symbolic links have their merits, and you should use a type of path that's appropriate for your particular application. Often, either a relative or absolute path will work just fine. The following example would have worked even after both files were moved:
<pre>
# cd /usr/bin
# ln -s keychain kc
# ls -l kc
lrwxrwxrwx 1 root root 8 Jan 5 12:40 kc -> keychain
# mv keychain kc /usr/local/bin
# ls -l /usr/local/bin/keychain
-rwxr-xr-x 1 root root 10150 Dec 12 20:09 /usr/local/bin/keychain
# ls -l /usr/local/bin/kc
lrwxrwxrwx 1 root root 17 Mar 27 17:44 kc -> keychain
</pre>
Now, we can run the keychain program by typing /usr/local/bin/kc. /usr/local/bin/kc points to the program keychain in the same directory as kc.

=== rm ===
Now that we know how to use cp, mv, and ln, it's time to learn how to remove objects from the file system. Normally, this is done with the rm command. To remove files, simply specify them on the command line:
<pre>
$ cd /tmp
$ touch file1 file2
$ ls -l file1 file2
-rw-r--r-- 1 root root 0 Jan 1 16:41 file1
-rw-r--r-- 1 root root 0 Jan 1 16:41 file2
$ rm file1 file2
$ ls -l file1 file2
ls: file1: No such file or directory
ls: file2: No such file or directory
</pre>
Note that under Linux, once a file is rm'ed, it's typically gone forever. For this reason, many junior system administrators will use the -i option when removing files. The -i option tells rm to remove all files in interactive mode -- that is, prompt before removing any file. For example:
<pre>
$ rm -i file1 file2
rm: remove regular empty file `file1'? y
rm: remove regular empty file `file2'? y
</pre>
In the above example, the rm command prompted whether or not the specified files should *really* be deleted. In order for them to be deleted, I had to type "y" and Enter twice. If I had typed "n", the file would not have been removed. Or, if I had done something really wrong, I could have typed Control-C to abort the rm -i command entirely -- all before it is able to do any potential damage to my system.

If you are still getting used to the rm command, it can be useful to add the following line to your ~/.bashrc file using your favorite text editor, and then log out and log back in. Then, any time you type rm, the bash shell will convert it automatically to an rm -i command. That way, rm will always work in interactive mode:
<pre>
alias rm="rm -i"
</pre>

=== rmdir ===
To remove directories, you have two options. You can remove all the objects inside the directory and then use rmdir to remove the directory itself:
<pre>
$ mkdir mydir
$ touch mydir/file1
$ rm mydir/file1
$ rmdir mydir
</pre>
This method is commonly referred to as "directory removal for suckers." All real power users and administrators worth their salt use the much more convenient rm -rf command, covered next.

The best way to remove a directory is to use the ''recursive force'' options of the rm command to tell rm to remove the directory you specify, as well as all objects contained in the directory:
<pre>
$ rm -rf mydir
</pre>
Generally, rm -rf is the preferred method of removing a directory tree. Be very careful when using rm -rf, since its power can be used for both good and evil :)

== Using Wild cards ==

=== Introducing Wild cards ===
In your day-to-day Linux use, there are many times when you may need to perform a single operation (such as rm) on many file system objects at once. In these situations, it can often be cumbersome to type in many files on the command line:
<pre>
$ rm file1 file2 file3 file4 file5 file6 file7 file8
</pre>
To solve this problem, you can take advantage of Linux' built-in wild card support. This support, also called "globbing" (for historical reasons), allows you to specify multiple files at once by using a wildcard pattern. Bash and other Linux commands will interpret this pattern by looking on disk and finding any files that match it. So, if you had files file1 through file8 in the current working directory, you could remove these files by typing:
<pre>
$ rm file[1-8]
</pre>
Or if you simply wanted to remove all files whose names begin with file as well as any file named file, you could type:
<pre>
$ rm file*
</pre>
The * wildcard matches any character or sequence of characters, or even "no character." Of course, glob wildcards can be used for more than simply removing files, as we'll see in the next panel.

=== Understanding non-matches ===
If you wanted to list all the file system objects in /etc beginning with g as well as any file called g, you could type:
<pre>
$ ls -d /etc/g*
/etc/gconf /etc/ggi /etc/gimp /etc/gnome /etc/gnome-vfs-mime-magic /etc/gpm /etc/group /etc/group-
</pre>
Now, what happens if you specify a pattern that doesn't match any file system objects? In the following example, we try to list all the files in /usr/bin that begin with asdf and end with jkl, including potentially the file asdfjkl:
<pre>
$ ls -d /usr/bin/asdf*jkl
ls: /usr/bin/asdf*jkl: No such file or directory
</pre>
Here's what happened. Normally, when we specify a pattern, that pattern matches one or more files on the underlying file system, and ''bash replaces the pattern with a space-separated list of all matching objects''. However, when the pattern doesn't produce any matches, ''bash leaves the argument, wild cards and all, as-is''. So, then ls can't find the file /usr/bin/asdf*jkl and it gives us an error. The operative rule here is that ''glob patterns are expanded only if they match objects in the file system''. Otherwise they remain as is and are passed literally to the program you're calling.

=== Wild card syntax: * and ? ===
Now that we've seen how globbing works, we should look at wild card syntax. You can use special characters for wild card expansion:

<nowiki>*</nowiki> will match zero or more characters. It means "anything can go here, including nothing". Examples:

* /etc/g* matches all files in /etc that begin with g, or a file called g.
* /tmp/my*1 matches all files in /tmp that begin with my and end with 1, including the file my1.

? matches any single character. Examples:

* myfile? matches any file whose name consists of myfile followed by a single character
* /tmp/notes?txt would match both /tmp/notes.txt and /tmp/notes_txt, if they exist

=== Wild card syntax: [] ===
This wild card is like a ?, but it allows more specificity. To use this wild card, place any characters you'd like to match inside the []. The resultant expression will match a single occurrence of any of these characters. You can also use - to specify a range, and even combine ranges. Examples:

* myfile[12] will match myfile1 and myfile2. The wild card will be expanded as long as at least one of these files exists in the current directory.
* [Cc]hange[Ll]og will match Changelog, ChangeLog, changeLog, and changelog. As you can see, using bracket wild cards can be useful for matching variations in capitalization.
* ls /etc/[0-9]* will list all files in /etc that begin with a number.
* ls /tmp/[A-Za-z]* will list all files in /tmp that begin with an upper or lower-case letter.

The [!] construct is similar to the [] construct, except rather than matching any characters inside the brackets, it'll match any character, as long as it is not listed between the [! and ]. Example:

* rm myfile[!9] will remove all files named myfile plus a single character, except for myfile9

=== Wild card caveats ===
Here are some caveats to watch out for when using wild cards. Since bash treats wild card-related characters (?, [, ], and *) specially, you need to take special care when typing in an argument to a command that contains these characters. For example, if you want to create a file that contains the string [fo]*, the following command may not do what you want:
<pre>
$ echo [fo]* > /tmp/mynewfile.txt
</pre>
If the pattern [fo]* matches any files in the current working directory, then you'll find the names of those files inside /tmp/mynewfile.txt rather than a literal [fo]* like you were expecting. The solution? Well, one approach is to surround your characters with single quotes, which tell bash to perform absolutely no wild card expansion on them:
<pre>
$ echo '[fo]*' > /tmp/mynewfile.txt
</pre>
Using this approach, your new file will contain a literal [fo]* as expected. Alternatively, you could use backslash escaping to tell bash that [, ], and * should be treated literally rather than as wild cards:
<pre>
$ echo \[fo\]\* > /tmp/mynewfile.txt
</pre>
Both approaches (single quotes and backslash escaping) have the same effect. Since we're talking about backslash expansion, now would be a good time to mention that in order to specify a literal \, you can either enclose it in single quotes as well, or type \\ instead (it will be expanded to \).
{{fancynote|Double quotes will work similarly to single quotes, but will still allow bash to do some limited expansion. Therefore, single quotes are your best bet when you are truly interested in passing literal text to a command. For more information on wild card expansion, type man 7 glob. For more information on quoting in bash, type man 8 glob and read the section titled QUOTING. If you're planning to take the LPI exams, consider this a homework assignment :)}}

== Summary and Resources ==

=== Summary ===
Congratulations; you've reached the end of our review of Linux fundamentals! I hope that it has helped you to firm up your foundational Linux knowledge. The topics you've learned here, including the basics of bash, basic Linux commands, links, and wild cards, have laid the groundwork for our next tutorial on basic administration, in which we'll cover topics like regular expressions, ownership and permissions, user account management, and more.

By continuing in this tutorial series, you'll soon be ready to attain your LPIC Level 1 Certification from the Linux Professional Institute. Speaking of LPIC certification, if this is something you're interested in, then we recommend that you study the Resources in the next panel, which have been carefully selected to augment the material covered in this tutorial.

=== Resources ===
Be sure to read the other articles in this series:
*[[Linux Fundamentals, Part 2]]
*[[Linux Fundamentals, Part 3]]
*[[Linux Fundamentals, Part 4]]

In the "Bash by Example" article series, Daniel shows you how to use bash programming constructs to write your own bash scripts. This series (particularly Parts 1 and 2) will be good preparation for the LPIC Level 1 exam:
* [[Bash by Example, Part 1]]: Fundamental programming in the Bourne-again shell
* [[Bash by Example, Part 2]]: More bash programming fundamentals
* [[Bash by Example, Part 3]]: Exploring the ebuild system

__NOTOC__
[[Category:Linux Core Concepts]]
[[Category:Articles]]

ZFS Install Guide

2013-01-22T23:10:14Z

Palica: /* Installing Funtoo */

{{fancywarning|This guide is a work in progress. Expect some quirks.}}

This tutorial will show you how to install Funtoo on ZFS (rootfs). This tutorial is meant to be an "overlay" over the [[Funtoo_Linux_Installation|Regular Funtoo Installation]]. Follow the normal installation and only use this guide for steps 2, 3, and 8.

{{fancyimportant|'''Since ZFS was really designed for 64 bit systems, we are only recommending and supporting 64 bit platforms and installations. We will not be supporting 32 bit platforms'''!}}

== Setting up your environment ==
In order for us to install Funtoo on ZFS, you will need an environment that provides the ZFS tools. We will be downloading two things:

# System Rescue CD,
# ZFS System Rescue Module (SRM)

This is just a file that when combined with System Rescue CD, gives you those tools.
<pre>
Name: SystemRescueCd-x86-3.2.0 (353 MiB)
Release Date: 2013-01-07
md5sum 90528f0c4b861363992fd9cbcc52d00a
</pre>

[https://sourceforge.net/projects/systemrescuecd/files/sysresccd-x86/3.2.0/systemrescuecd-x86-3.2.0.iso/download Download System Rescue CD 3.2.0] 
[http://jonathanvasquez.com/files/sysresccd/ Download the ZFS System Rescue Module]

[[Creating_System_Rescue_CD_Modules|Follow the instructions here to download and place the srm into your flash drive]].
== Creating partitions ==
There are two ways to partition your disk: You can use your entire drive and let ZFS automatically partition it for you, or you can do it manually.

Using your entire disk drive is recommended since ZFS turns on/off a few settings. For one, if you use your whole-disk, ZFS will set the I/O elevator for the drive automatically. On Solaris machines, ZFS also enables the disk's write cache.

If you partition it manually, you should set your I/O scheduler to no-op so it doesn't conflict with the ZFS scheduler. Partitioning manually also gives you the advantage of putting your /boot outside the ZFS pool so that you can use a bootloader that doesn't support booting from ZFS.
=== Whole Disk ===
This is the easiest method and the recommended method. 
First lets make sure that the disk is completely wiped from any previous disk labels and partitions.
We will also assume that <tt>/dev/sda</tt> is the target drive. 
<console>
# ##i##gdisk /dev/sda

Command: ##i##x ↵
Expert command: ##i##z ↵
About to wipe out GPT on /dev/sda. Proceed?: ##i##y ↵
GPT data structures destroyed! You may now partition the disk using fdisk or other utilities.
Blank out MBR?: ##i##y ↵
</console>
{{fancywarning|This is a destructive operation. Make sure you really don't want anything on this disk.}}
Now that we have a clean drive, we will create the new pool in it while letting zfs automatically partition it.

Create the pool as normal:
<console>
# ##i##zpool create -f -o ashift=12 -o cachefile= -O compression=on -m none -R /mnt/funtoo rpool /dev/sda
</console>
Doing this will let ZFS create a GPT style disk with two partitions. We will also slightly modify this to add a BIOS Boot Partition so that grub can be installed successfully. First lets export the pool so that the kernel can use the new partition table without rebooting.
<console>
# ##i##zpool export rpool
</console>

And now lets create a new BIOS Boot Partition at partition 2 from sectors '''48''' to '''2047''':
<console>
# ##i##gdisk /dev/sda

Command (? for help): ##i##p ↵

Number Start (sector) End (sector) Size Code Name
1 2048 16758783 8.0 GiB BF01 zfs
9 16758784 16775167 8.0 MiB BF07

Command: ##i##n ↵
Partition number: ##i##2 ↵
First sector: ##i##48 ↵
Last sector: ##i##2047 ↵
Hex code or GUID: ##i##EF02 ↵

Command: ##i##w ↵
Do you want to proceed? (Y/N): ##i##y
OK; writing new GUID partition table (GPT) to /dev/sda.
The operation has completed successfully.
</console>

If you were to check <tt>/dev/sda</tt> again, you would see these 3 partitions:
<console>
Number Start (sector) End (sector) Size Code Name
1 2048 16758783 8.0 GiB BF01 zfs
2 48 2047 1000.0 KiB EF02 BIOS boot partition
9 16758784 16775167 8.0 MiB BF07
</console>

Let's import the pool again:
<console>
# ##i##zpool import -f -o cachefile= -R /mnt/funtoo rpool
</console>

[[ZFS_Install_Guide#Create_the_zfs_datasets|Now continue with creating your datasets.]]
=== Manual partitioning ===
==== fdisk (MBR Style) ====
'''Create Partition 1''' (boot):
<console>
Command: ##i##n ↵
Partition type: ##i##↵
Partition number: ##i##↵
First sector: ##i##↵
Last sector: ##i##+250M ↵
</console>

'''Create Partition 2''' (ZFS):
<console>
Command: ##i##n ↵
Partition type: ##i##↵
Partition number: ##i##↵
First sector: ##i##↵
Last sector: ##i##↵

Command: ##i##t ↵
Partition number: ##i##2 ↵
Hex code: ##i##bf ↵

Command: ##i##p ↵

Device Boot Start End Blocks Id System
/dev/sda1 2048 514047 256000 83 Linux
/dev/sda2 514048 1953525167 976505560 bf Solaris
</console>

==== gdisk (GPT Style) ====
'''Create Partition 1''' (boot):
<console>
Command: ##i##n ↵
Partition Number: ##i##↵
First sector: ##i##↵
Last sector: ##i##+250M ↵
Hex Code: ##i##↵
</console>

'''Create Partition 2''' (BIOS Boot Partition):
<console>Command: ##i##n ↵
Partition Number: ##i##↵
First sector: ##i##↵
Last sector: ##i##+32M ↵
Hex Code: ##i##EF02 ↵
</console>
{{fancyimportant|Only make the above BIOS Boot Partition if you are using GRUB 2 on GPT. If you are using the extlinux bootloader, this partition is not necessary.}}

'''Create Partition 2''' (ZFS):
<console>Command: ##i##n ↵
Partition Number: ##i##↵
First sector: ##i##↵
Last sector: ##i##↵
Hex Code: ##i##bf01 ↵

Command: ##i##p ↵

Number Start (sector) End (sector) Size Code Name
1 2048 514047 250.0 MiB 8300 Linux filesystem
2 514048 1953525134 931.3 GiB BF01 Solaris /usr & Mac ZFS

Command: ##i##w ↵
</console>

=== Format your boot volume ===
If you did manual partitioning, format your separate boot partition:
<console># ##i##mkfs.ext4 /dev/sda1</console>

=== Create the zpool ===
We will first create the pool. The pool will be named `rpool` and the disk will be aligned to 4096 (using ashift=12)

<console># ##i##zpool create -f -o ashift=12 -o cachefile= -O compression=on -m none -R /mnt/funtoo rpool /dev/sda2</console>
{{fancyimportant|If you followed the manual GPT partitioning instructions, you should change /dev/sda2 to /dev/sda3.}}{{fancynote|If you have a previous pool that you would like to import, you can do a: '''zpool import -f -R /mnt/funtoo <pool_name>'''}}

=== Create the zfs datasets ===
We will now create some datasets. For this installation, we will create a small but future proof amount of datasets. We will have a dataset for the OS (/), and your swap. We will also show you how to create some optional datasets: /home, /var, /usr/src, and /usr/portage.

<console>
Create some empty containers for organization purposes, and make the dataset that will hold /
# ##i##zfs create -o mountpoint=none rpool/ROOT
# ##i##zfs create -o mountpoint=/ rpool/ROOT/funtoo

Optional, but recommended datasets: /home, /root
# ##i##zfs create -o mountpoint=/home rpool/HOME
# ##i##zfs create -o mountpoint=/root rpool/HOME/root

Optional datasets: /usr/src, /var
# ##i##zfs create -o mountpoint=none rpool/FUNTOO
# ##i##zfs create -o mountpoint=/usr/src rpool/FUNTOO/src
# ##i##zfs create -o mountpoint=/var rpool/FUNTOO/var
</console>

==== Creating a separate portage dataset (optional) ====
Creating a separate portage dataset could be useful if you would like to keep your portage tree, distfiles (source code files), and packages (your compiled binaries if you have FEATURES="buildpkg" enabled) in a safe place (or if you want to back up this directory up easily). This requires a few extra steps because we can't just do a regular emerge --sync when we initially chroot. We will need to download a portage snapshot tarball and extract it into the directory. The required steps for getting and extracting the snapshot will be shown later on in the guide once you chroot into the environment.

For now just create the datasets:
<console>
# ##i##zfs create -o mountpoint=/usr/portage -o compression=off rpool/FUNTOO/portage
# ##i##zfs create -o mountpoint=/usr/portage/distfiles -o compression=off rpool/FUNTOO/distfiles
</console>

=== Create your swap zvol ===
'''Make your swap +1G greater than your RAM. An 8G machine would have 9G of RAM (This is kinda big though).'''
<console>
# ##i##zfs create -o sync=always -o primarycache=metadata -o secondarycache=none -V 9G rpool/swap
</console>

=== Format your swap zvol ===
<console>
# ##i##mkswap -f /dev/zvol/rpool/swap
# ##i##swapon /dev/zvol/rpool/swap
</console>

=== Last minute checks and touches ===
Check to make sure everything appears fine:
<console>
# ##i##zpool status
# ##i##zfs list
</console>

Copy the '''zpool.cache''' file to your new environment.
<console>
# ##i##mkdir -p /mnt/funtoo/etc/zfs
# ##i##cp /etc/zfs/zpool.cache /mnt/funtoo/etc/zfs
</console>

Make an empty mtab file
<console># ##i##touch /mnt/funtoo/etc/mtab</console>

Now we will continue to install funtoo.
== Installing Funtoo ==
[[Funtoo_Linux_Installation|Download and install the Funtoo stage3 and continue installation as normal.]]

Then chroot into your new funtoo environment:
<console>
# ##i##cd /mnt/funtoo

Mount your boot drive ** You don't need to do this if you're using whole-disk zfs **
# ##i##mount /dev/sda1 /mnt/funtoo/boot

Bind the kernel related directories
# ##i##mount --rbind /proc proc
# ##i##mount --rbind /dev dev
# ##i##mount --rbind /sys sys

Copy network settings
# ##i##cp /etc/resolv.conf etc/chroot into your new funtoo environment
# ##i##env -i HOME=/root TERM=$TERM chroot . /bin/bash -l
</console>

=== Syncing your portage tree ===
==== If you didn't create a separate portage dataset, then just sync your portage tree as normal. ====
<console># ##i##emerge --sync</console>

==== If you did create a separate portage dataset, let's now get the portage snapshot set up. ====
<console>
Change into your /usr directory
# ##i##cd /usr

Download and extract the portage snapshot
# ##i##wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/portage-latest.tar.xz
# ##i##tar xf portage-latest.tar.xz

Change into your portage directory and checkout the funtoo branch
# ##i##cd portage
# ##i##git checkout funtoo.org

Now sync your portage tree
# ##i##emerge --sync
</console>

== Kernel Configuration ==
{{fancynote|The below configurations are the requirements for "Bliss Initramfs Creator". Some of these might not be needed for genkernel.}}

Tested with kernel 2.6.32, 3.2.34, 3.6.9, 3.7.[1-3].

When you get up to the kernel, make sure that you disable the CFQ scheduler, and turn on No-op (It's the default one once you disable all schedulers). The reason for this is because ZFS has its own scheduler and the CFQ one conflicts with it. Go to your kernel config, and make sure you have the following: (there should be a /usr/src/linux symlink as well)

<pre>ZLIB_INFLATE/DEFLATE must be compiled into the kernel (not as a module).
> ZLIB_INFLATE [=y], ZLIB_DEFLATE [=y]

General setup --->
> [*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
> () Initramfs source file(s)
[*] Enable loadable module support --->
[*] Module unloading
Enable the block layer --->
IO Schedulers --->
< > Deadline I/O scheduler
< > CFQ I/O scheduler
Default I/O scheduler (No-op)

Device Drivers --->
> Generic Driver Options --->
>> [*] Maintain a devtmpfs filesystem to mount at /dev
>> [*] Automount devtmpfs at /dev, after the kernel mounted the rootfs

Cryptographic API --->
<*> Deflate compression algorithm
<*> Zlib compression algorithm

* All other drivers required to see your PATA/SATA drives must be compiled in.</pre>

Continue and compile/install your kernel:
<console>
# ##i##make bzImage modules
# ##i##make install
# ##i##make modules_install
</console>

== Installing the ZFS userspace tools ==

<console># ##i##emerge -av zfs</console>

Check to make sure that the zfs tools are working, the zpool.cache file that you copied before should be displayed.<console>
# ##i##zpool status
# ##i##zfs list
</console>

If everything worked, continue.

== Install the bootloader ==

=== GRUB 2 ===
If you are using whole-disk zfs then you will need grub2 because grub2 is the only bootloader that supports booting from a zfs pool.

Before you do this, make sure this checklist is followed:
* Installed kernel and kernel modules
* Installed zfs package from the tree
* /dev, /proc, /sys are mounted in the chroot environment

Once all this is checked, let's install grub2. First we need to enable the "libzfs" use flag so zfs support is compiled for grub2.

<console># ##i##echo "sys-boot/grub libzfs" >> /etc/portage/package.use</console>

Then we will compile grub2:
{{fancyimportant|GRUB should be _at least_ version 2.0.0 since 2.0.0 added zfs support. 1.99,.98 will not work.}}
<console># ##i##emerge -av grub</console>

Once this is done, you can check that grub is version 2.00 by doing the following command:
<console>
# ##i##grub-install --version
grub-install (GRUB) 2.00
</console>

Now try to install grub2:
<console># ##i##grub-install --no-floppy /dev/sda</console>

You should receive the following message
<console>Installation finished. No error reported.</console>

If not, then go back to the above checklist.
=== Extlinux ===
There are four things we need to do for extlinux:

# Install extlinux bootloader
# Write the .bin to the front of the target disk
# Toggle BIOS partition flag
# Write a extlinux configuration file

First emerge extlinux:
<console># ##i##emerge -av syslinux</console>

Then create a /boot/extlinux directory:
<console>
# ##i##cd /boot
# ##i##mkdir /boot/extlinux
</console>

Change into the extlinux dir and install the bootloader:
<console>
# ##i##cd /boot/extlinux
# ##i##extlinux --install .
</console>

==== MBR ====
<console>
# ##i##fdisk /dev/sda

Command: ##i##a ↵
Partition number: ##i##1 ↵
Command: ##i##w ↵
</console>

Printing the <tt>fdisk</tt> partition layout should show a star next to <tt>/dev/sda1</tt>:
<console>/dev/sda * 2048 514047 256000 83 Linux</console>

Flash the .bin to the front of the disk:
<console># ##i##dd conv=notrunc bs=440 count=1 if=/usr/share/syslinux/mbr.bin of=/dev/sda</console>

=== GPT ===
<console># ##i##sgdisk /dev/sda --attributes=1:set:2</console>

Flash the .bin to the front of the disk:
<console># ##i##dd conv=notrunc bs=440 count=1 if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</console>

We will write the extlinux/grub configuration file in the next section.
== Create the initramfs ==
There are two ways to do this, you can use genkernel, or you can use my bliss initramfs creator. I will show you both.

=== genkernel ===
<console>
# ##i##emerge -av sys-kernel/genkernel
# ##i##genkernel --zfs initramfs
</console>

<pre>
Example: kernel name is: vmlinuz-3.7.3-ALL
initramfs name is: initramfs-genkernel-x86_64-3.7.3-ALL
pool name is: rpool
</pre>

'''grub.cfg''':
<console>
set timeout=3
set default=0

# Funtoo
menuentry "Funtoo - 3.7.3" {
insmod zfs
linux /ROOT/funtoo/@/boot/vmlinuz-3.7.3-ALL root=rpool/ROOT/funtoo real_root=ZFS=rpool/ROOT/funtoo dozfs=force
initrd /ROOT/funtoo/@/boot/initramfs-genkernel-x86_64-3.7.3-ALL
}
</console>

'''extlinux.conf''':
<console>
LABEL funtoo
MENU LABEL Funtoo 3.7.3-ALL
KERNEL /boot/vmlinuz-3.7.3-ALL
INITRD /boot/initramfs-genkernel-x86_64-3.7.3-ALL
APPEND real_root=ZFS=rpool/ROOT/funtoo dozfs=force
</console>

=== Bliss Initramfs Creator ===
Clone my creator which is located at: git://github.com/fearedbliss/Bliss-Initramfs-Creator.git

<console># ##i##git clone git://github.com/fearedbliss/Bliss-Initramfs-Creator.git</console>

Then go into this new directory, run the script as root, and place it into /boot:
<console># ##i##cd Bliss-Initramfs-Creator
# ##i##./createInit
# ##i##mv initrd-<kernel_name>.img /boot
</console>

'''<kernel_name>''' is the name of what you selected in the initramfs creator, and the name of the outputted file. Once you do this just go to your bootloader config, and add it in there.

<pre>
Example: Kernel name is: vmlinuz-3.7.3-ALL
initramfs name is: initrd-3.7.3-ALL.img
Pool root is: rpool/ROOT/funtoo
</pre>

'''grub.cfg''':
<console>
set timeout=3
set default=0

# Funtoo
menuentry "Funtoo - 3.7.3" {
insmod zfs
linux /ROOT/funtoo/@/boot/vmlinuz-3.7.3-ALL root=rpool/ROOT/funtoo quiet
initrd /ROOT/funtoo/@/boot/initrd-3.7.3-ALL.img
}
</console>

'''extlinux.conf:'''
<console>
LABEL funtoo
MENU LABEL Funtoo 3.7.3-ALL
KERNEL /boot/vmlinuz-3.7.3-ALL
INITRD /boot/initrd-3.7.3-ALL.img
APPEND root=rpool/ROOT/funtoo
</console>

== Final configuration ==
=== Add the zfs tools to openrc ===
<console># ##i##rc-update add zfs boot</console>

=== Add filesystems to /etc/fstab ===
<console>
# ##i##nano /etc/fstab

# <fs> <mountpoint> <type> <opts> <dump/pass>
# Do not add the /boot line below if you are using whole-disk zfs
/dev/sda1 /boot ext4 defaults 1 2
/dev/zvol/rpool/swap none swap sw 0 0
</console>

=== Clean up and reboot ===
We are almost done, we are just going to clean up, '''set our root password''', and unmount whatever we mounted and get out.

<console>
Delete the stage3/portage tarballs you downloaded earlier so they don't take up space.
# ##i##cd /
# ##i##rm stage3-latest.tar.xz
# ##i##rm /usr/portage-latest.tar.xz

Set your root password
# ##i##passwd
>> Enter your password, you won't see what you are writing (for security reasons), but it is there!

Get out of the chroot environment
# ##i##exit

Unmount all the kernel filesystem stuff and boot (if you have a separate /boot)
# ##i##cd /mnt/funtoo
# ##i##umount -l proc dev sys boot

Turn off the swap
# ##i##swapoff /dev/zvol/rpool/swap

Export the zpool
# ##i##cd /
# ##i##zpool export -f rpool

Reboot
# ##i##reboot
</console>

{{fancyimportant|'''Don't forget to set your root password as stated above before exiting chroot and rebooting. If you don't set the root password, you won't be able to log into your new system.'''}}

and that should be enough to get your system to boot on ZFS.

== Extra: After reboot ==
After you restart your machine and your inside your desktop, continue to set up anything you need in terms of /etc configurations. Once you have everything the way you like it, take a snapshot of your system. You will be using this snapshot to revert back to this state if anything ever happens to your system down the road. The snapshots are cheap, and almost instant.

To take the snapshot of your rootfs, type the following:
<console># ##i##zfs snapshot rpool/ROOT/funtoo@install</console>

To see if your snapshot was taken, type:
<console># ##i##zfs list -t snapshot</console>

If your machine ever fails and you need to get back to this state, just type:
<console># ##i##zfs rollback rpool/ROOT/funtoo@install</console>

=== Recovery Environment ===
On ZFS it is extremely easy to create a recovery environment using an already working snapshot. So that's what we will be doing. Create a clone of the @install snapshot which you will use for recovery purposes. If something happens to your main install, you can boot into this clone and fix the main one. One of the differences (maybe the only difference) between a clone and a snapshot is that a clone is rewritable while a snapshot is only read-only.

<console># ##i##zfs clone rpool/ROOT/funtoo@install rpool/ROOT/recovery</console>

==== Add the clone to your grub.cfg ====

<console>
set timeout=3
set default=0

# Funtoo Recovery
menuentry "Funtoo Recovery - 3.7.3" {
insmod zfs
linux /ROOT/funtoo/@/boot/vmlinuz-3.7.3-ALL root=rpool/ROOT/recovery quiet
initrd /ROOT/funtoo/@/boot/initrd-3.7.3-ALL.img
}
</console>

==== Add the clone to your extlinux.conf ====
<console>
LABEL funtoo-recovery
MENU LABEL Funtoo Recovery
KERNEL /boot/vmlinuz-3.7.3-ALL
INITRD /boot/initrd-3.7.3-ALL.img
APPEND root=rpool/ROOT/recovery
</console>

==== Things to watch out for ====
Since your recovery clone will tend to get old as you use your main system, and since your recovery and other stuff are on the same pool, we don't want the new pool stuff to be mounted when we launch recovery. We also don't want video drivers to be conflicting.
# Make sure that nvidia/nouveau stuff are blacklisted.
# Make sure that your /boot and /lib/modules for the kernel in your 'recovery' are matching.
# Disable the zfs openrc script so that nothing else gets automatically mounted. Only your rootfs.

You can do the above stuff by mounting your copy and chrooting into it.

<console>
Mount the recovery clone
# ##i##mkdir /mnt/recovery
# ##i##mount -t zfs -o zfsutil rpool/ROOT/recovery /mnt/recovery
# ##i##cd /mnt/recovery

Mount the kernel devices
# ##i##mount --rbind /proc ./proc
# ##i##mount --rbind /dev ./dev
# ##i##mount --rbind /sys ./sys

Copy zpool.cache
# ##i##cp /etc/zfs/zpool.cache etc/zfs

Chroot into the new environment
# ##i##env -i HOME=/root TERM=$TERM chroot . bash --login

Disable zfs/zfs-shutdown openrc scripts
# ##i##rc-config delete zfs boot

Blacklist nouveau/nvidia drivers
# ##i##echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
# ##i##echo "blacklist nvidia" >> /etc/modprobe.d/blacklist.conf
</console>

Once you are done doing your changes, just umount and exit the chroot:

<console>
# ##i##cd /
# ##i##umount -l proc dev sys
# ##i##exit
</console>

==== Getting into the recovery ====
Just start your machine and pick the '''Funtoo Recovery''' option from the Boot Menu.

Enjoy your new install on ZFS :)

[[Category:HOWTO]]
[[Category:Filesystems]]
[[Category:Featured]]

Linux Containers

2013-01-22T22:57:21Z

Palica: /* /etc/lxc/funtoo/fstab */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
<console>
# ##i##CONFIG=/path/to/config /usr/sbin/lxc-checkconfig
</console>

=== Emerge lxc ===
<console>
# ##i##emerge -av app-emulation/lxc
</console>
=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo LXC template, and unpack it to a directory such as <tt>/var/lib/lxc/funtoo</tt>.
# Create an empty <tt>/var/lib/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/var/lib/lxc/funtoo/etc/inittab</tt>.

That's almost all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
## Container
lxc.utsname = funtoo
lxc.rootfs = /var/lib/lxc/funtoo
lxc.arch = x86_64
lxc.tty = 6
lxc.pts = 1024
#lxc.console = /var/log/lxc/funtoo.console

## Capabilities
lxc.cap.drop = sys_admin sys_module mac_admin mac_override

## Devices
# Allow all devices
#lxc.cgroup.devices.allow = a
# Deny all devices
lxc.cgroup.devices.deny = a
# Allow to mknod all devices (but not using them)
lxc.cgroup.devices.allow = c *:* m
lxc.cgroup.devices.allow = b *:* m
# /dev/console
lxc.cgroup.devices.allow = c 5:1 rwm
# /dev/fuse
lxc.cgroup.devices.allow = c 10:229 rwm
# /dev/null
lxc.cgroup.devices.allow = c 1:3 rwm
# /dev/ptmx
lxc.cgroup.devices.allow = c 5:2 rwm
# /dev/pts/*
lxc.cgroup.devices.allow = c 136:* rwm
# /dev/random
lxc.cgroup.devices.allow = c 1:8 rwm
# /dev/rtc
lxc.cgroup.devices.allow = c 254:0 rwm
# /dev/tty
lxc.cgroup.devices.allow = c 5:0 rwm
# /dev/urandom
lxc.cgroup.devices.allow = c 1:9 rwm
# /dev/zero
lxc.cgroup.devices.allow = c 1:5 rwm

## Limits#
lxc.cgroup.cpu.shares = 1024
#lxc.cgroup.cpuset.cpus = 0
#lxc.cgroup.memory.limit_in_bytes = 256M
#lxc.cgroup.memory.memsw.limit_in_bytes = 1G

## Filesystem
lxc.mount = /etc/lxc/funtoo/fstab
#lxc.mount.entry = proc /var/lib/lxc/example.org/rootfs/proc proc nodev,noexec,nosuid 0 0
#lxc.mount.entry = sysfs /var/lib/lxc/example.org/rootfs/sys sysfs defaults,ro 0 0
#lxc.mount.entry = /srv/share/example.org /var/lib/example.org/rootfs/srv/example.org none defaults,bind 0 0

## Network
lxc.network.type = veth
lxc.network.flags = up
lxc.network.hwaddr = #put your MAC address here, otherwise you will get a random one
lxc.network.link = br0
lxc.network.name = eth0
#lxc.network.veth.pair = veth-example
</pre>

Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Linux Containers

2013-01-22T22:56:20Z

Palica: /* /etc/lxc/funtoo/config */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
<console>
# ##i##CONFIG=/path/to/config /usr/sbin/lxc-checkconfig
</console>

=== Emerge lxc ===
<console>
# ##i##emerge -av app-emulation/lxc
</console>
=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo LXC template, and unpack it to a directory such as <tt>/var/lib/lxc/funtoo</tt>.
# Create an empty <tt>/var/lib/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/var/lib/lxc/funtoo/etc/inittab</tt>.

That's almost all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
## Container
lxc.utsname = funtoo
lxc.rootfs = /var/lib/lxc/funtoo
lxc.arch = x86_64
lxc.tty = 6
lxc.pts = 1024
#lxc.console = /var/log/lxc/funtoo.console

## Capabilities
lxc.cap.drop = sys_admin sys_module mac_admin mac_override

## Devices
# Allow all devices
#lxc.cgroup.devices.allow = a
# Deny all devices
lxc.cgroup.devices.deny = a
# Allow to mknod all devices (but not using them)
lxc.cgroup.devices.allow = c *:* m
lxc.cgroup.devices.allow = b *:* m
# /dev/console
lxc.cgroup.devices.allow = c 5:1 rwm
# /dev/fuse
lxc.cgroup.devices.allow = c 10:229 rwm
# /dev/null
lxc.cgroup.devices.allow = c 1:3 rwm
# /dev/ptmx
lxc.cgroup.devices.allow = c 5:2 rwm
# /dev/pts/*
lxc.cgroup.devices.allow = c 136:* rwm
# /dev/random
lxc.cgroup.devices.allow = c 1:8 rwm
# /dev/rtc
lxc.cgroup.devices.allow = c 254:0 rwm
# /dev/tty
lxc.cgroup.devices.allow = c 5:0 rwm
# /dev/urandom
lxc.cgroup.devices.allow = c 1:9 rwm
# /dev/zero
lxc.cgroup.devices.allow = c 1:5 rwm

## Limits#
lxc.cgroup.cpu.shares = 1024
#lxc.cgroup.cpuset.cpus = 0
#lxc.cgroup.memory.limit_in_bytes = 256M
#lxc.cgroup.memory.memsw.limit_in_bytes = 1G

## Filesystem
lxc.mount = /etc/lxc/funtoo/fstab
#lxc.mount.entry = proc /var/lib/lxc/example.org/rootfs/proc proc nodev,noexec,nosuid 0 0
#lxc.mount.entry = sysfs /var/lib/lxc/example.org/rootfs/sys sysfs defaults,ro 0 0
#lxc.mount.entry = /srv/share/example.org /var/lib/example.org/rootfs/srv/example.org none defaults,bind 0 0

## Network
lxc.network.type = veth
lxc.network.flags = up
lxc.network.hwaddr = #put your MAC address here, otherwise you will get a random one
lxc.network.link = br0
lxc.network.name = eth0
#lxc.network.veth.pair = veth-example
</pre>

Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
none /lxc/funtoo/libexec/rc/init.d tmpfs rw,mode=755 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Linux Containers

2013-01-22T22:51:33Z

Palica: /* /etc/lxc/funtoo/config */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
<console>
# ##i##CONFIG=/path/to/config /usr/sbin/lxc-checkconfig
</console>

=== Emerge lxc ===
<console>
# ##i##emerge -av app-emulation/lxc
</console>
=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo LXC template, and unpack it to a directory such as <tt>/var/lib/lxc/funtoo</tt>.
# Create an empty <tt>/var/lib/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/var/lib/lxc/funtoo/etc/inittab</tt>.

That's almost all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
## Containerlxc.utsname = funtoolxc.rootfs = /var/lib/lxc/funtoolxc.arch = x86_64lxc.tty = 6lxc.pts = 1024#lxc.console = /var/log/lxc/funtoo.console## Capabilitieslxc.cap.drop = sys_admin sys_module mac_admin mac_override## Devices# Allow all devices#lxc.cgroup.devices.allow = a# Deny all deviceslxc.cgroup.devices.deny = a# Allow to mknod all devices (but not using them)lxc.cgroup.devices.allow = c *:* mlxc.cgroup.devices.allow = b *:* m# /dev/consolelxc.cgroup.devices.allow = c 5:1 rwm# /dev/fuselxc.cgroup.devices.allow = c 10:229 rwm# /dev/nulllxc.cgroup.devices.allow = c 1:3 rwm# /dev/ptmxlxc.cgroup.devices.allow = c 5:2 rwm# /dev/pts/*lxc.cgroup.devices.allow = c 136:* rwm# /dev/randomlxc.cgroup.devices.allow = c 1:8 rwm# /dev/rtclxc.cgroup.devices.allow = c 254:0 rwm
# /dev/ttylxc.cgroup.devices.allow = c 5:0 rwm# /dev/urandomlxc.cgroup.devices.allow = c 1:9 rwm# /dev/zerolxc.cgroup.devices.allow = c 1:5 rwm## Limits#lxc.cgroup.cpu.shares = 1024#lxc.cgroup.cpuset.cpus = 0#lxc.cgroup.memory.limit_in_bytes = 256M#lxc.cgroup.memory.memsw.limit_in_bytes = 1G## Filesystemlxc.mount = /etc/lxc/funtoo/fstab#lxc.mount.entry = proc /var/lib/lxc/example.org/rootfs/proc proc nodev,noexec,nosuid 0 0#lxc.mount.entry = sysfs /var/lib/lxc/example.org/rootfs/sys sysfs defaults,ro 0 0#lxc.mount.entry = /srv/share/example.org /var/lib/example.org/rootfs/srv/example.org none defaults,bind 0 0## Networklxc.network.type = vethlxc.network.flags = uplxc.network.hwaddr = #put your MAC address here, otherwise you will get a random onelxc.network.link = br0lxc.network.name = eth0#lxc.network.veth.pair = veth-example
</pre>

Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
none /lxc/funtoo/libexec/rc/init.d tmpfs rw,mode=755 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Linux Containers

2013-01-22T22:19:40Z

Palica: /* Create and Configure Container Filesystem */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
<console>
# ##i##CONFIG=/path/to/config /usr/sbin/lxc-checkconfig
</console>

=== Emerge lxc ===
<console>
# ##i##emerge -av app-emulation/lxc
</console>
=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo LXC template, and unpack it to a directory such as <tt>/var/lib/lxc/funtoo</tt>.
# Create an empty <tt>/var/lib/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/var/lib/lxc/funtoo/etc/inittab</tt>.

That's almost all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
lxc.utsname = funtoo
lxc.arch = x86_64

# mount configuration
lxc.mount = /etc/lxc/funtoo/fstab
lxc.rootfs = /lxc/funtoo

# network configuration
lxc.network.type = veth
lxc.network.flags = up
lxc.network.link = brwan
lxc.network.ipv4 = <your IPv4 address here, like 1.2.3.4/29>
lxc.network.hwaddr = <your randomly-generated MAC address here, like a2:97:b6:df:df:28>
lxc.network.name = eth0

# CPU & Memory Limits
# kernel/Documentation/cgroups/cpusets.txt # cores 0,1 of your CPU
lxc.cgroup.cpuset.cpus = 0,1
lxc.cgroup.cpu.shares = 1024
# kernel/Documentation/cgroups/memory.txt
lxc.cgroup.memory.limit_in_bytes = 1024M
lxc.cgroup.memory.memsw.limit_in_bytes = 2048M

# TTY configuration
lxc.tty = 12
lxc.pts = 128

# Device configuration:
# Deny access to all devices:
lxc.cgroup.devices.deny = a
# Allow only the following devices to be opened:
lxc.cgroup.devices.allow = c 1:3 rwm # dev/null
lxc.cgroup.devices.allow = c 1:5 rwm # dev/zero
lxc.cgroup.devices.allow = c 1:8 rwm # dev/random
lxc.cgroup.devices.allow = c 1:9 rwm # dev/urandom
lxc.cgroup.devices.allow = c 5:0 rwm # /dev/tty - allows ssh-add/password input
lxc.cgroup.devices.allow = c 5:1 rwm # /dev/console - allows lxc-start output
lxc.cgroup.devices.allow = c 254:0 rwm # rtc

# TTYs - we create only 3 TTYs: tty0, tty1, tty2 - you can create up to 12 (see lxc.tty = 12)
lxc.cgroup.devices.allow = c 4:0 rwm # /dev/tty0
lxc.cgroup.devices.allow = c 4:1 rwm # /dev/tty1
lxc.cgroup.devices.allow = c 4:2 rwm # /dev/tty2

# pts namespaces
lxc.cgroup.devices.allow = c 136:* rwm # dev/pts/*
lxc.cgroup.devices.allow = c 5:2 rwm # dev/pts/ptmx

# restrict capabilities:
lxc.cap.drop = audit_control
lxc.cap.drop = audit_write
lxc.cap.drop = mac_admin
lxc.cap.drop = mac_override
lxc.cap.drop = setpcap
lxc.cap.drop = sys_admin
lxc.cap.drop = sys_boot
lxc.cap.drop = sys_module
lxc.cap.drop = sys_rawio
lxc.cap.drop = sys_time
# By default, don't use lxc.cap.drop = mknod. This will allow mknod to create
# device nodes so build scripts and other things don't fail. Then, we'll
# rely on the devices.deny settings (default deny) to prevent any created
# device nodes inside the container from being used to access the host's
# hardware:
# lxc.cap.drop = mknod
</pre>
Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
none /lxc/funtoo/libexec/rc/init.d tmpfs rw,mode=755 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Linux Containers

2013-01-22T22:14:23Z

Palica: /* Install LXC kernel */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
<console>
# ##i##CONFIG=/path/to/config /usr/sbin/lxc-checkconfig
</console>

=== Emerge lxc ===
<console>
# ##i##emerge -av app-emulation/lxc
</console>
=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo OpenVZ template, and unpack it to a directory such as <tt>/lxc/funtoo</tt>.
# Edit <tt>/lxc/funtoo/etc/rc.conf</tt> and change <tt>rc_sys=openvz</tt> to <tt>rc_sys=lxc</tt>.
# Create an empty <tt>/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/lxc/funtoo/etc/inittab</tt>.
# Edit <tt>udev-mount</tt>, <tt>udev-postmount</tt> and <tt>udev-save</tt> and change the <tt>keyword</tt> line to have the arguments <tt>-openvz -vserver -lxc</tt>. (will be fixed in about a week)

That's all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
lxc.utsname = funtoo
lxc.arch = x86_64

# mount configuration
lxc.mount = /etc/lxc/funtoo/fstab
lxc.rootfs = /lxc/funtoo

# network configuration
lxc.network.type = veth
lxc.network.flags = up
lxc.network.link = brwan
lxc.network.ipv4 = <your IPv4 address here, like 1.2.3.4/29>
lxc.network.hwaddr = <your randomly-generated MAC address here, like a2:97:b6:df:df:28>
lxc.network.name = eth0

# CPU & Memory Limits
# kernel/Documentation/cgroups/cpusets.txt # cores 0,1 of your CPU
lxc.cgroup.cpuset.cpus = 0,1
lxc.cgroup.cpu.shares = 1024
# kernel/Documentation/cgroups/memory.txt
lxc.cgroup.memory.limit_in_bytes = 1024M
lxc.cgroup.memory.memsw.limit_in_bytes = 2048M

# TTY configuration
lxc.tty = 12
lxc.pts = 128

# Device configuration:
# Deny access to all devices:
lxc.cgroup.devices.deny = a
# Allow only the following devices to be opened:
lxc.cgroup.devices.allow = c 1:3 rwm # dev/null
lxc.cgroup.devices.allow = c 1:5 rwm # dev/zero
lxc.cgroup.devices.allow = c 1:8 rwm # dev/random
lxc.cgroup.devices.allow = c 1:9 rwm # dev/urandom
lxc.cgroup.devices.allow = c 5:0 rwm # /dev/tty - allows ssh-add/password input
lxc.cgroup.devices.allow = c 5:1 rwm # /dev/console - allows lxc-start output
lxc.cgroup.devices.allow = c 254:0 rwm # rtc

# TTYs - we create only 3 TTYs: tty0, tty1, tty2 - you can create up to 12 (see lxc.tty = 12)
lxc.cgroup.devices.allow = c 4:0 rwm # /dev/tty0
lxc.cgroup.devices.allow = c 4:1 rwm # /dev/tty1
lxc.cgroup.devices.allow = c 4:2 rwm # /dev/tty2

# pts namespaces
lxc.cgroup.devices.allow = c 136:* rwm # dev/pts/*
lxc.cgroup.devices.allow = c 5:2 rwm # dev/pts/ptmx

# restrict capabilities:
lxc.cap.drop = audit_control
lxc.cap.drop = audit_write
lxc.cap.drop = mac_admin
lxc.cap.drop = mac_override
lxc.cap.drop = setpcap
lxc.cap.drop = sys_admin
lxc.cap.drop = sys_boot
lxc.cap.drop = sys_module
lxc.cap.drop = sys_rawio
lxc.cap.drop = sys_time
# By default, don't use lxc.cap.drop = mknod. This will allow mknod to create
# device nodes so build scripts and other things don't fail. Then, we'll
# rely on the devices.deny settings (default deny) to prevent any created
# device nodes inside the container from being used to access the host's
# hardware:
# lxc.cap.drop = mknod
</pre>
Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
none /lxc/funtoo/libexec/rc/init.d tmpfs rw,mode=755 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Linux Containers

2013-01-22T22:13:11Z

Palica: /* Configuring the Funtoo Host System */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
<console>
# ##i##CONFIG=/path/to/config /usr/sbin/lxc-checkconfig

</console>

=== Emerge lxc ===
<console>
# ##i##emerge -av app-emulation/lxc
</console>
=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo OpenVZ template, and unpack it to a directory such as <tt>/lxc/funtoo</tt>.
# Edit <tt>/lxc/funtoo/etc/rc.conf</tt> and change <tt>rc_sys=openvz</tt> to <tt>rc_sys=lxc</tt>.
# Create an empty <tt>/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/lxc/funtoo/etc/inittab</tt>.
# Edit <tt>udev-mount</tt>, <tt>udev-postmount</tt> and <tt>udev-save</tt> and change the <tt>keyword</tt> line to have the arguments <tt>-openvz -vserver -lxc</tt>. (will be fixed in about a week)

That's all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
lxc.utsname = funtoo
lxc.arch = x86_64

# mount configuration
lxc.mount = /etc/lxc/funtoo/fstab
lxc.rootfs = /lxc/funtoo

# network configuration
lxc.network.type = veth
lxc.network.flags = up
lxc.network.link = brwan
lxc.network.ipv4 = <your IPv4 address here, like 1.2.3.4/29>
lxc.network.hwaddr = <your randomly-generated MAC address here, like a2:97:b6:df:df:28>
lxc.network.name = eth0

# CPU & Memory Limits
# kernel/Documentation/cgroups/cpusets.txt # cores 0,1 of your CPU
lxc.cgroup.cpuset.cpus = 0,1
lxc.cgroup.cpu.shares = 1024
# kernel/Documentation/cgroups/memory.txt
lxc.cgroup.memory.limit_in_bytes = 1024M
lxc.cgroup.memory.memsw.limit_in_bytes = 2048M

# TTY configuration
lxc.tty = 12
lxc.pts = 128

# Device configuration:
# Deny access to all devices:
lxc.cgroup.devices.deny = a
# Allow only the following devices to be opened:
lxc.cgroup.devices.allow = c 1:3 rwm # dev/null
lxc.cgroup.devices.allow = c 1:5 rwm # dev/zero
lxc.cgroup.devices.allow = c 1:8 rwm # dev/random
lxc.cgroup.devices.allow = c 1:9 rwm # dev/urandom
lxc.cgroup.devices.allow = c 5:0 rwm # /dev/tty - allows ssh-add/password input
lxc.cgroup.devices.allow = c 5:1 rwm # /dev/console - allows lxc-start output
lxc.cgroup.devices.allow = c 254:0 rwm # rtc

# TTYs - we create only 3 TTYs: tty0, tty1, tty2 - you can create up to 12 (see lxc.tty = 12)
lxc.cgroup.devices.allow = c 4:0 rwm # /dev/tty0
lxc.cgroup.devices.allow = c 4:1 rwm # /dev/tty1
lxc.cgroup.devices.allow = c 4:2 rwm # /dev/tty2

# pts namespaces
lxc.cgroup.devices.allow = c 136:* rwm # dev/pts/*
lxc.cgroup.devices.allow = c 5:2 rwm # dev/pts/ptmx

# restrict capabilities:
lxc.cap.drop = audit_control
lxc.cap.drop = audit_write
lxc.cap.drop = mac_admin
lxc.cap.drop = mac_override
lxc.cap.drop = setpcap
lxc.cap.drop = sys_admin
lxc.cap.drop = sys_boot
lxc.cap.drop = sys_module
lxc.cap.drop = sys_rawio
lxc.cap.drop = sys_time
# By default, don't use lxc.cap.drop = mknod. This will allow mknod to create
# device nodes so build scripts and other things don't fail. Then, we'll
# rely on the devices.deny settings (default deny) to prevent any created
# device nodes inside the container from being used to access the host's
# hardware:
# lxc.cap.drop = mknod
</pre>
Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
none /lxc/funtoo/libexec/rc/init.d tmpfs rw,mode=755 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Linux Containers

2013-01-22T22:09:26Z

Palica: /* Emerge lxc */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
CONFIG=/path/to/config /usr/sbin/lxc-checkconfig

=== Emerge lxc ===
emerge -av app-emulation/lxc

=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo OpenVZ template, and unpack it to a directory such as <tt>/lxc/funtoo</tt>.
# Edit <tt>/lxc/funtoo/etc/rc.conf</tt> and change <tt>rc_sys=openvz</tt> to <tt>rc_sys=lxc</tt>.
# Create an empty <tt>/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/lxc/funtoo/etc/inittab</tt>.
# Edit <tt>udev-mount</tt>, <tt>udev-postmount</tt> and <tt>udev-save</tt> and change the <tt>keyword</tt> line to have the arguments <tt>-openvz -vserver -lxc</tt>. (will be fixed in about a week)

That's all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
lxc.utsname = funtoo
lxc.arch = x86_64

# mount configuration
lxc.mount = /etc/lxc/funtoo/fstab
lxc.rootfs = /lxc/funtoo

# network configuration
lxc.network.type = veth
lxc.network.flags = up
lxc.network.link = brwan
lxc.network.ipv4 = <your IPv4 address here, like 1.2.3.4/29>
lxc.network.hwaddr = <your randomly-generated MAC address here, like a2:97:b6:df:df:28>
lxc.network.name = eth0

# CPU & Memory Limits
# kernel/Documentation/cgroups/cpusets.txt # cores 0,1 of your CPU
lxc.cgroup.cpuset.cpus = 0,1
lxc.cgroup.cpu.shares = 1024
# kernel/Documentation/cgroups/memory.txt
lxc.cgroup.memory.limit_in_bytes = 1024M
lxc.cgroup.memory.memsw.limit_in_bytes = 2048M

# TTY configuration
lxc.tty = 12
lxc.pts = 128

# Device configuration:
# Deny access to all devices:
lxc.cgroup.devices.deny = a
# Allow only the following devices to be opened:
lxc.cgroup.devices.allow = c 1:3 rwm # dev/null
lxc.cgroup.devices.allow = c 1:5 rwm # dev/zero
lxc.cgroup.devices.allow = c 1:8 rwm # dev/random
lxc.cgroup.devices.allow = c 1:9 rwm # dev/urandom
lxc.cgroup.devices.allow = c 5:0 rwm # /dev/tty - allows ssh-add/password input
lxc.cgroup.devices.allow = c 5:1 rwm # /dev/console - allows lxc-start output
lxc.cgroup.devices.allow = c 254:0 rwm # rtc

# TTYs - we create only 3 TTYs: tty0, tty1, tty2 - you can create up to 12 (see lxc.tty = 12)
lxc.cgroup.devices.allow = c 4:0 rwm # /dev/tty0
lxc.cgroup.devices.allow = c 4:1 rwm # /dev/tty1
lxc.cgroup.devices.allow = c 4:2 rwm # /dev/tty2

# pts namespaces
lxc.cgroup.devices.allow = c 136:* rwm # dev/pts/*
lxc.cgroup.devices.allow = c 5:2 rwm # dev/pts/ptmx

# restrict capabilities:
lxc.cap.drop = audit_control
lxc.cap.drop = audit_write
lxc.cap.drop = mac_admin
lxc.cap.drop = mac_override
lxc.cap.drop = setpcap
lxc.cap.drop = sys_admin
lxc.cap.drop = sys_boot
lxc.cap.drop = sys_module
lxc.cap.drop = sys_rawio
lxc.cap.drop = sys_time
# By default, don't use lxc.cap.drop = mknod. This will allow mknod to create
# device nodes so build scripts and other things don't fail. Then, we'll
# rely on the devices.deny settings (default deny) to prevent any created
# device nodes inside the container from being used to access the host's
# hardware:
# lxc.cap.drop = mknod
</pre>
Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
none /lxc/funtoo/libexec/rc/init.d tmpfs rw,mode=755 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Linux Containers

2013-01-22T22:08:18Z

Palica: /* Configuring the Funtoo Host System */

Linux Containers, or LXC, is a Linux feature that allows Linux to run one or more isolated virtual systems (with their own network interfaces, process namespace, user namespace, and power state) using a single Linux kernel on a single server.

== Status ==

As of Linux kernel 3.1.5, LXC is usable for isolating your own private workloads from one another. It is not yet ready to isolate potentially malicious users from one another or the host system. For a more mature containers solution that is appropriate for hosting environments, see [[OpenVZ]].

LXC containers don't yet have their own system uptime, and they see everything that's in the host's <tt>dmesg</tt> output, among other things. But in general, the technology works.

== Configuring the Funtoo Host System ==

=== Install LXC kernel ===
Any kernel beyond 3.1.5 will probably work. Personally I prefer the sys-kernel/gentoo-sources-3.4.9 as these have support for all the namespaces without sacrificing the xfs, FUSE or NFS support for example. These checks were introduced later starting from kernel 3.5, this could also mean that the user namespace is not working optimally.

* User namespace (EXPERIMENTAL) depends on EXPERIMENTAL and on UIDGID_CONVERTED
** config UIDGID_CONVERTED
*** True if all of the selected software components are known to have uid_t and gid_t converted to kuid_t and kgid_t where appropriate and are otherwise safe to use with the user namespace.
**** Networking - depends on NET_9P = n
**** Filesystems - 9P_FS = n, AFS_FS = n, AUTOFS4_FS = n, CEPH_FS = n, CIFS = n, CODA_FS = n, FUSE_FS = n, GFS2_FS = n, NCP_FS = n, NFSD = n, NFS_FS = n, OCFS2_FS = n, XFS_FS = n

==== Kernel configuration ====
These options should be enable in your kernel to be able to take full advantage of LXC.

* General setup
** CONFIG_NAMESPACES
*** CONFIG_UTS_NS
*** CONFIG_IPC_NS
*** CONFIG_PID_NS
*** CONFIG_NET_NS
*** CONFIG_USER_NS
** CONFIG_CGROUPS
*** CONFIG_CGROUP_DEVICE
*** CONFIG_CGROUP_SCHED
*** CONFIG_CGROUP_CPUACCT
*** CONFIG_CGROUP_MEM_RES_CTLR
*** CONFIG_CPUSETS (on multiprocessor hosts)
* Networking support
** Networking options
*** CONFIG_VLAN_8021Q
* Device Drivers
** Character devices
*** Unix98 PTY support
**** CONFIG_DEVPTS_MULTIPLE_INSTANCES
** Network device support
*** Network core driver support
**** CONFIG_VETH
**** CONFIG_MACVLAN

Once you have lxc installed, you can then check your kernel config with:
CONFIG=/path/to/config /usr/sbin/lxc-checkconfig

=== Emerge lxc ===

=== Configure Networking For Container ===

Typically, one uses a bridge to allow containers to connect to the network. This is how to do it under Funtoo Linux:

# create a bridge using the Funtoo network configuration scripts. Name the bridge something like <tt>brwan</tt> (using <tt>/etc/init.d/netif.brwan</tt>). Configure your bridge to have an IP address.
# Make your physical interface, such as <tt>eth0</tt>, an interface with no IP address (use the Funtoo <tt>interface-noip</tt> template.)
# Make <tt>netif.eth0</tt> a slave of <tt>netif.brwan</tt> in <tt>/etc/conf.d/netif.brwan</tt>.
# Enable your new bridged network and make sure it is functioning properly on the host.

You will now be able to configure LXC to automatically add your container's virtual ethernet interface to the bridge when it starts, which will connect it to your network.

== Setting up a Funtoo Linux LXC Container ==

Here are the steps required to get Funtoo Linux running inside a container. The steps below show you how to set up a container using an existing Funtoo Linux OpenVZ template. It is now also possible to use [[Metro]] to build an lxc container tarball directly, which will save you manual configuration steps and will provide an <tt>/etc/fstab.lxc</tt> file that you can use for your host container config. See [[Metro Recipes]] for info on how to use Metro to generate an lxc container.

=== Create and Configure Container Filesystem ===

# Start with a Funtoo OpenVZ template, and unpack it to a directory such as <tt>/lxc/funtoo</tt>.
# Edit <tt>/lxc/funtoo/etc/rc.conf</tt> and change <tt>rc_sys=openvz</tt> to <tt>rc_sys=lxc</tt>.
# Create an empty <tt>/lxc/funtoo/etc/fstab</tt> file.
# Ensure <tt>c1</tt> line is uncommented (enabled) and <tt>c2</tt> through <tt>c6</tt> lines are disabled in <tt>/lxc/funtoo/etc/inittab</tt>.
# Edit <tt>udev-mount</tt>, <tt>udev-postmount</tt> and <tt>udev-save</tt> and change the <tt>keyword</tt> line to have the arguments <tt>-openvz -vserver -lxc</tt>. (will be fixed in about a week)

That's all you need to get the container filesystem ready to start.

=== Create Container Configuration Files ===

Create the following files:

==== <tt>/etc/lxc/funtoo/config</tt> ====

{{fancynote|Daniel Robbins needs to update this config to be more in line with http://wiki.progress-linux.org/software/lxc/ -- this config appears to have nice, refined device node permissions and other goodies.}}

Read "man 5 lxc.conf" , to get more information about linux container configuration file.
<pre>
lxc.utsname = funtoo
lxc.arch = x86_64

# mount configuration
lxc.mount = /etc/lxc/funtoo/fstab
lxc.rootfs = /lxc/funtoo

# network configuration
lxc.network.type = veth
lxc.network.flags = up
lxc.network.link = brwan
lxc.network.ipv4 = <your IPv4 address here, like 1.2.3.4/29>
lxc.network.hwaddr = <your randomly-generated MAC address here, like a2:97:b6:df:df:28>
lxc.network.name = eth0

# CPU & Memory Limits
# kernel/Documentation/cgroups/cpusets.txt # cores 0,1 of your CPU
lxc.cgroup.cpuset.cpus = 0,1
lxc.cgroup.cpu.shares = 1024
# kernel/Documentation/cgroups/memory.txt
lxc.cgroup.memory.limit_in_bytes = 1024M
lxc.cgroup.memory.memsw.limit_in_bytes = 2048M

# TTY configuration
lxc.tty = 12
lxc.pts = 128

# Device configuration:
# Deny access to all devices:
lxc.cgroup.devices.deny = a
# Allow only the following devices to be opened:
lxc.cgroup.devices.allow = c 1:3 rwm # dev/null
lxc.cgroup.devices.allow = c 1:5 rwm # dev/zero
lxc.cgroup.devices.allow = c 1:8 rwm # dev/random
lxc.cgroup.devices.allow = c 1:9 rwm # dev/urandom
lxc.cgroup.devices.allow = c 5:0 rwm # /dev/tty - allows ssh-add/password input
lxc.cgroup.devices.allow = c 5:1 rwm # /dev/console - allows lxc-start output
lxc.cgroup.devices.allow = c 254:0 rwm # rtc

# TTYs - we create only 3 TTYs: tty0, tty1, tty2 - you can create up to 12 (see lxc.tty = 12)
lxc.cgroup.devices.allow = c 4:0 rwm # /dev/tty0
lxc.cgroup.devices.allow = c 4:1 rwm # /dev/tty1
lxc.cgroup.devices.allow = c 4:2 rwm # /dev/tty2

# pts namespaces
lxc.cgroup.devices.allow = c 136:* rwm # dev/pts/*
lxc.cgroup.devices.allow = c 5:2 rwm # dev/pts/ptmx

# restrict capabilities:
lxc.cap.drop = audit_control
lxc.cap.drop = audit_write
lxc.cap.drop = mac_admin
lxc.cap.drop = mac_override
lxc.cap.drop = setpcap
lxc.cap.drop = sys_admin
lxc.cap.drop = sys_boot
lxc.cap.drop = sys_module
lxc.cap.drop = sys_rawio
lxc.cap.drop = sys_time
# By default, don't use lxc.cap.drop = mknod. This will allow mknod to create
# device nodes so build scripts and other things don't fail. Then, we'll
# rely on the devices.deny settings (default deny) to prevent any created
# device nodes inside the container from being used to access the host's
# hardware:
# lxc.cap.drop = mknod
</pre>
Read "man 7 capabilities" to get more information aboout Linux capabilities.

Above, use the following command to generate a random MAC for <tt>lxc.network.hwaddr</tt>:

<pre>
# openssl rand -hex 6 | sed 's/$..$/\1:/g; s/.$//'
</pre>

It is a very good idea to assign a static MAC address to your container using <tt>lxc.network.hwaddr</tt>. If you don't, LXC will auto-generate a new random MAC every time your container starts, which may confuse network equipment that expects MAC addresses to remain constant.

It might happen from case to case that you aren't able to start your LXC Container with the above generated MAC address so for all these who run into that problem here is a little script that connects your IP for the container with the MAC address. Just save the following code as <tt>/etc/lxc/hwaddr.sh</tt>, make it executable and run it like <tt>/etc/lxc/hwaddr.sh xxx.xxx.xxx.xxx</tt> where xxx.xxx.xxx.xxx represents your Container IP.

<pre>
#!/bin/sh
IP=$*
HA=`printf "02:00:%x:%x:%x:%x" ${IP//./ }`
echo $HA
</pre>

==== <tt>/etc/lxc/funtoo/fstab</tt> ====

<pre>
none /lxc/funtoo/dev/pts devpts defaults 0 0
none /lxc/funtoo/proc proc defaults 0 0
none /lxc/funtoo/sys sysfs defaults 0 0
none /lxc/funtoo/dev/shm tmpfs nodev,nosuid,noexec,mode=1777,rw 0 0
none /lxc/funtoo/libexec/rc/init.d tmpfs rw,mode=755 0 0
</pre>

== Initializing and Starting the Container ==

You will probably need to set the root password for the container before you can log in. You can use chroot to do this quickly:

<pre>
# chroot /lxc/funtoo
(chroot) # passwd
New password: XXXXXXXX
Retype new password: XXXXXXXX
passwd: password updated successfully
# exit
</pre>

Now that the root password is set, run:

<pre>
# lxc-start -n funtoo -d
</pre>

The <tt>-d</tt> option will cause it to run in the background.

To attach to the console:

<pre>
# lxc-console -n funtoo
</pre>

You should now be able to log in and use the container. In addition, the container should now be accessible on the network.

To stop the container:

<pre>
# lxc-stop -n funtoo
</pre>

Ensure that networking is working from within the container while it is running, and you're good to go!

== LXC Bugs/Missing Features ==

This section is devoted to documenting issues with the current implementation of LXC and its associated tools. We will be gradually expanding this section with detailed descriptions of problems, their status, and proposed solutions.

=== reboot ===

By default, lxc does not support rebooting a container from within. It will simply stop and the host will not know to start it.

=== PID namespaces ===

Process ID namespaces are functional, but the container can still see the CPU utilization of the host via the system load (ie. in <tt>top</tt>).

=== /dev/pts newinstance ===

* Some changes may be required to the host to properly implement "newinstance" <tt>/dev/pts</tt>. See [https://bugzilla.redhat.com/show_bug.cgi?id=501718 This Red Hat bug].

=== lxc-create and lxc-destroy ===

* LXC's shell scripts are badly designed and are sure way to destruction, avoid using lxc-create and lxc-destroy.

=== network initialization and cleanup ===

* If used network.type = phys after lxc-stop the interface will be renamed to value from lxc.network.link. It supposed to be fixed in 0.7.4, happens still on 0.7.5 - http://www.mail-archive.com/lxc-users@lists.sourceforge.net/msg01760.html

* Re-starting a container can result in a failure as network resource are tied up from the already-defunct instance: [http://www.mail-archive.com/lxc-devel@lists.sourceforge.net/msg00824.html]

=== lxc-halt ===

* Missing tool to graceful shutdown container. 'lxc-halt' should be written and be posix sh-compatible, using lxc-execute to run halt in container.

=== funtoo ===

* Our udev should be updated to contain <tt>-lxc</tt> in scripts. (This has been done as of 02-Nov-2011, so should be resolved. But not fixed in our openvz templates, so need to regen them in a few days.)
* Our openrc should be patched to handle the case where it cannot mount tmpfs, and gracefully handle this situation somehow. (Work-around in our docs above, which is to mount tmpfs to <tt>/libexec/rc/init.d</tt> using the container-specific <tt>fstab</tt> file (on the host.)
* Emerging udev within a container can/will fail when realdev is run, if a device node cannot be created (such as /dev/console) if there are no mknod capabilities within the container. This should be fixed.

== References ==

* <tt>man 7 capabilities</tt>
* <tt>man 5 lxc.conf</tt>

== Links ==

* There are a number of additional lxc features that can be enabled via patches: [http://lxc.sourceforge.net/patches/linux/3.0.0/3.0.0-lxc1/]
* [https://wiki.ubuntu.com/UserNamespace Ubuntu User Namespaces page]
* lxc-gentoo setup script [https://github.com/globalcitizen/lxc-gentoo on GitHub]

* '''IBM developerWorks'''
** [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/index.html LXC: Linux Container Tools]
** [http://www.ibm.com/developerworks/linux/library/l-lxc-security/ Secure Linux Containers Cookbook]

* '''Linux Weekly News'''
** [http://lwn.net/Articles/244531/ Smack for simplified access control]

[[Category:Labs]]
[[Category:HOWTO]]
[[Category:Virtualization]]

Forking An Ebuild

2013-01-21T21:18:59Z

Palica:

Often, a Funtoo developer needs to fork an upstream ebuild. This is necessary when we want to apply fixes to it. This page will explain the concepts of forking and how this works in the context of Funtoo.

== Portage Tree Generation ==

Funtoo Linux generates its Portage tree using a special script that essentially takes a Gentoo tree as its starting point, and then applies various modifications to it. The modifications involve adding packages from various overlays, including our [[Overlay:Funtoo-overlay]]. Some packages added are brand new, while other packages are our special forked versions that replace existing packages.

In the vast majority of cases, when we fork a package, we take full responsibility for all ebuilds associated with that package, meaning that we have a full copy of the <tt>sys-foo/bar</tt> directory in one of our overlays.

If you're interested in seeing the actual script that does all these things, take a look at the following files:

; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/current-update.sh: cronned script that calls <tt>merge.py</tt>.
;http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge.py: python script that does the heavy lifting of combining Gentoo tree with various overlays, including our flora and funtoo-overlay. When we want to change what overlays we merge, what packages we exclude as a matter of policy (such as stale packages in some overlays), we make changes to this file.
; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge_utils.py: python module that contains classes and methods that implement the merging functionality.

== Forking an Ebuild ==

In general, we fork ebuilds from Gentoo that we want to modify in some way. Before you fork an ebuild, it's important to understand that in general we fork entire packages, not just a single ebuild. This means that if you want to make some changes to <tt>sys-foo/bar</tt>, you are going to fork all <tt>sys-foo/bar</tt> ebuilds, and then Funtoo will be responsible for continuing to maintain these ebuilds until the package is unforked. Here are the steps we would use to fork <tt>sys-foo/bar</tt>:

# Find <tt>sys-foo/bar</tt> in you regular Portage tree. Make sure you have run <tt>emerge --sync</tt> recently to ensure it is up-to-date. If you want to fork from very recent changes that are not yet in our tree, you may need to grab the most recent Gentoo Portage tree to serve as your source for <tt>sys-foo/bar</tt> (this typically isn't necessary.)
# Copy the <tt>sys-foo/bar</tt> directory in its entirety to <tt>funtoo-overlay/sys-foo/bar</tt>.
# Make any necessary modifications to <tt>funtoo-overlay/sys-foo/bar</tt>.
# Perform some funtoo-ification steps prior to commit.
# Add and commit the changes to funtoo-overlay.
# Push changes to funtoo-overlay.

At this point, the forked <tt>sys-foo/bar</tt> package will be part of funtoo-overlay. The next time our unified Portage tree is generated by <tt>merge.py</tt> (the one that users have in their <tt>/usr/portage</tt> and is updated via <tt>emerge --sync</tt>), your forked ebuild will be used in place of the Gentoo ebuild. Why is this? It is because our <tt>merge.py</tt> script has been defined with a policy that any ebuilds in funtoo-overlay will replace any existing Gentoo ebuilds if they exist. The mechanism of replacement is that our <tt>sys-foo/bar</tt> directory will be used in place of Gentoo's <tt>sys-foo/bar</tt> directory. So this is how the forking process works.

== Funtoo-ification ==

When we fork a package from Gentoo, we perform the following tweaks to the package directory before committing:

# Removal of <tt>ChangeLog</tt>.
# Run <tt>ebuild foo-1.0.ebuild digest</tt> before committing. This will cause the <tt>Manifest</tt> file to be regenerated. Gentoo has a lot more entries in this file than we do, since we use mini-Manfiests that only include DIST listings (for distfiles only.) We want to commit our mini-Manifest (still called <tt>Manifest</tt>, just with less entries in it) rather than the one that came from Gentoo.
# Edit the top of each ebuild, and remove all <tt>Copyright</tt> and <tt>$Header:</tt> lines at the top of the file. We have a LICENSE.txt and COPYRIGHT.txt file in the root of our Portage tree, which is easier to maintain than keeping all the years up-to-date in each ebuild. Also, the <tt>$Header:</tt> line is there for the CVS version control system in Gentoo which Funtoo does not use. ''The only comment that should remain on the top of the ebuild is the one stating that it is distributed under the GPLv2.''.

Here are a few additional changes that you are allowed to make to any forked ebuilds:

# Line length greater than 80 characters. Gentoo enforces an 80-character line length limit. We don't.
# <tt>KEYWORDS</tt> of <tt>*</tt> and <tt>~*</tt>. Gentoo does not allow these shortcuts. We do. They allow you to say "all arches" and "all unstable arches" in a concise way. Gentoo doesn't allow these shortcuts because it's Gentoo's policy to have each arch team manually approve each package. We do not have this policy so we can use the shortcuts.
# Use of <tt>4-python</tt> EAPI. We allow the use of this EAPI for enhanced python functionality.

[[Category:Development]]

ZFS Fun

2013-01-21T21:17:06Z

Palica:

= Introduction =

== ZFS features and limitations ==

ZFS offers an impressive amount of features even putting aside its hybrid nature (both a filesystem and a volume manager -- zvol) covered in detail on [http://en.wikipedia.org/wiki/ZFS Wikipedia]. One of the most fundamental points to keep in mind about ZFS is it '''targets a legendary reliability in terms of preserving data integrity'''. ZFS uses several techniques to detect and repair (self-healing) corrupted data, simply speaking it makes an aggressive use of checksums and relies on data redundancy, the price pay is it requires a bit more CPU processing power than traditional filesystems and RAID solution. However, the [http://en.wikipedia.org/wiki/ZFS Wikipedia article about ZFS] also mention it is strongly discouraged to use ZFS over classic RAID arrays as it can not control the data redundancy,thus ruining most of its benefits.

In short, ZFS has the following features (not exhaustive):

* Storage pool (if you are used to BTRFS volumes should be familiar)
* Plenty of space:
** 256 zettabytes per storage pool (2^64 storages pools max in a system).
** 16 exabytes max for a single file
** 2^48 entries max per directory
* Virtual block-devices support support over a ZFS pool (zvol) - (extremely cool when jointly used over a RAID-Z volume)
* Read-only Snapshot support (it is possible to get a read-write copy of them, those are named clones)
* Encryption support (supported only at ZFS version 30 and upper, ZFS version 31 is shipped with Oracle Solaris 11 so that version is mandatory if you plan to encrypt your ZFS datasets/pools)
* Built-in''' RAID-5-like-over-steroid capabilities known as [http://en.wikipedia.org/wiki/Non-standard_RAID_levels#RAID-Z RAID-Z] and RAID-6-like-over-steroid capabilities known as RAID-Z2'''. RAID-Z3 (triple parity) also exists.
* Copy-on-Write transactional filesystem
* Meta-attributes support (properties) allowing you to you easily drive the show like "That directory is encrypted", "that directory is limited to 5GiB", "That directory is exported via NFS" and so on. Depending on what you define, ZFS takes the appropriates actions!
* Dynamic striping to optimize data throughput
* Variable block length
* Data duplication
* Automatic pool re-silvering
* Transparent data compression / encryption (later requires Solaris 11)

Most notable limitations are:

* Lack a features ZFS developers knows as "Block Pointer rewrite functionality" (planned to be developed), without it ZFS suffers of currently not being able to:
** Pool defragmentation (COW techniques used in ZFS mitigates the problem)
** Pool resizing
** Data compression (re-applying)
** Adding an additional device in a RAID-Z/Z2/Z3 pool to increase it size (however, it is possible to replace in sequence each one of the disks composing a RAID-Z/Z2/Z3)
* '''NOT A CLUSTERED FILESYSTEM''' like Lustre, GFS or OCFS2
* No data healing if used on a single device (corruption can still be detected), workaround if to force a data duplication on the drive
* No support of TRIMming (SSD devices)

== ZFS on well known operating systems ==

=== Linux ===

Despite the source code of ZFS is open, its license (Sun CDDL) is incompatible with the license governing the Linux kernel (GNU GPL v2) thus preventing its direct integration. However a couple of ports exists, but suffers of maturity and lack of features. As of writing (September 2011) two known implementations exists:

* [http://zfs-fuse.net ZFS-fuse]: a totally userland implementation relying on FUSE. Funtoo provides the version 0.7.0 in its portage tree. Worth mentioning at its subject that:
** It supports zpool version 23
** It has improved robustness and stability
** It does not support zvols (feature not planned in a near future according project roadmap

* [http://zfsonlinux.org ZFS on Linux]: a native implementation of ZFS in kernel mode. The project claims to have ''"a functional and stable SPA, DMU, ZVOL, and Posix Layer (ZPL)"''. Current upstream version is 0.6.0-rc5 (can mount ZFS filesystems and support zpool version 28), however neither Gentoo and Funtoo have ebuilds for this port (yet). As ZFS on Linux is an out-of-tree Linux kernel implementation, patches must be waited after each Linux kernel release. As of september 2011, the project claims to have '''support for Linux 2.6.26 up to Linux 3.0.0''', Linux 3.1 series kernels are not officially supported and ZFS on Linux is far from being mature and usable on production systems. It suffers from a couple of major issues like:
** <s>Crash when used with a preemptable kernel (see [https://github.com/zfsonlinux/zfs/issues/83 issue 83])</s> Fixed Aug 27, 2012
** <s>Deadlocks can happen with some debug options (see [https://github.com/zfsonlinux/zfs/issues/167 issue 167])</s> Fixed Oct 19, 2011

=== Solaris/OpenIndiana ===

* '''Oracle Solaris:''' remains the de facto reference platform for ZFS implementation: ZFS on this platform is now considered as mature and usable on production systems. Solaris 11 uses ZFS even for its "system" pool (aka ''rpool''). A great advantage of this: it is now quite easy to revert the effect of a patch at the condition a snapshot has been taken just before applying it. In the "old good" times of Solaris 10 and before, reverting a patch was possible but could be tricky and complex when possible. ZFS is far from being new in Solaris as it takes its roots in 2005 to be, then, integrated in Solaris 10 6/06 introduced in June 2006.

* '''[http://openindiana.org OpenIndiana]:''' is based on the Illuminos kernel (a derivative of the now defunct OpenSolaris) which aims to provide absolute binary compatibility with Sun/Oracle Solaris. Worth mentioning that Solaris kernel and the [https://www.illumos.org Illumos kernel] were both sharing the same code base, however, they now follows a different path since Oracle announced the discontinuation of OpenSolaris (August 13th 2010). Like Oracle Solaris, OpenIndiana uses ZFS for its system pool. The illumos kernel ZFS support lags a bit behind Oracle: it supports zpool version 28 where as Oracle Solaris 11 has zpool version 31 support, data encryption being supported at zpool version 30.

=== *BSD ===

* '''FreeBSD''': ZFS is present in FreeBSD since FreeBSD 7 (zpool version 6) and FreeBSD can boot on a ZFS volume (zfsboot). ZFS support has been vastly enhanced in FreeBSD 8.x (8.2 supports zpool version 15, version 8.3 will support version 28) and FreeBSD 9 (supporting zpool version 28). ZFS in FreeBSD is now considered as fully functional and mature. FreeBSD derivatives such as the popular [http://www.freenas.org FreeNAS] takes befenits of ZFS and integrated it in their tools. In the case of that latter, it have, for example, supports for zvol though its Web management interface (FreeNAS >= 8.0.1).

* '''NetBSD''': ZFS has been started to be ported as a GSoC project in 2007 and is present in the NetBSD mainstream since 2009 (zpool version 13).

* '''OpenBSD''': No ZFS support yet and not planned until Oracle changes some policies according to the project FAQ.

== ZFS alternatives ==

* WAFL seems to have severe limitation [http://unixconsult.org/wafl/ZFS%20vs%20WAFL.html] (document is not dated), also an interesting article lies [http://blogs.netapp.com/dave/2008/12/is-wafl-a-files.html here]
* BTRFS is advancing every week but it still lacks such features like the capability of emulating a virtual block device over a storage pool (zvol) and it has a built-in support for RAID-0/1 only. At date of writing, it is still experimental where as ZFS is used on big production servers.
* VxFS has also been targeted by comparisons like [http://blogs.oracle.com/dom/entry/zfs_v_vxfs_iozone this one] (a bit [http://www.symantec.com/connect/blogs/suns-comparision-vxfs-and-zfs-scalability-flawed controversial]). VxFS has been known in the industry since 1993 and is known for its legendary flexibility. Symantec acquired VxFS and proposed a basic version (no clustering for example) of it under the same [http://www.symantec.com/enterprise/sfbasic/index.jsp Veritas Storage Foundation Basic]
* An interesting discussion about modern filesystems can be found on [http://www.osnews.com/story/19665/Solaris_Filesystem_Choices OSNews.com]

== ZFS vs BTRFS ==

BTRFS and ZFS are sibbling in their concepts and of course have differences:
* both are transactional filesystems (in BTRFS a a transaction is a sequence of low level operations)
* both implement for example the pool concept (called a "volume" in BTRFS)
* both can do snapshots although in ZFS a snapshot is a read only thing and its attributes can't be modified. BTRFS on the other hand has writable snapshots (known as clones in ZFS)
* both can organize their storage pool in several logical divisions (called datasets in ZFS and subvolumes in BTRFS).
* As their equivalent in BTRFS (subvolumes), ZFS datasets appears as directories
* Where as a ZFS snapshot is "hidden" in a sub-directory (named .zfs), BTRFS snapshots appears as visible directories
* While ZFS manages rollback in a transparent manner (the filesystem knows where and how to rollback the data), rollingback data in BTRFS requires a bit more work as the system administrator must umount/remount a BTRFS subvolume.
* ZFS has a kind of sophisticated RAID-5 called RAID-Z (and now RAID-Z2 ~ RAID-6), similar capabilities are planned for BTRFS but not yet available as of september 2011
* A ZFS filesytem can be snapshotted and sent through the network, BTRFS has not yet reach that integration level
* Whereas ZFS makes an aggressive use of properties to govern the behaviour of the different datasets (quotas, sharing over NFS, encryption, compression and so on), BTRFS does not use this notion or in a much light manner and only through the ''mount'' command.
* '''ZFS has no journal (!)''', this is not a design flaw but an interesting intrinsic feature :) See page 7 of [http://hub.opensolaris.org/bin/download/Community+Group+zfs/docs/zfslast.pdf ''"ZFS The last word on filesystems"'']. Also worth mentioning that BTRFS still lacks a viable filesystem checking tool (announced in august 2011) and sometimes crashes when an invalid log is encountered. BTRFS tools present in experimental branches can however mitigate the problem by allowing the system administrator to clear the BTRFS log in case of a disaster happen (see our article [http://www.funtoo.org/wiki/BTRFS_Fun#Recovering_an_apparent_dead_BTRFS_filesystem BTRFS Fun]).

= ZFS resource naming restrictions =

Before going further, you must be aware of restrictions concerning the names you can use on a ZFS filesystem. The general rule is: you can can use all of the alphanumeric characters plus the following specials are allowed:
* Underscore (_)
* Hyphen (-)
* Colon (:)
* Period (.)

The name used to designate a ZFS pool has no particular restriction except:
* it can't use one the reserved words in particular:
** ''mirror''
** ''raidz'' (''raidz2'', ''raidz3'' and so on)
** ''spare''
** ''cache''
** ''log''
* names must begin with an alphanumeric character (same for ZFS datasets).

= Playing with ZFS =
== Requirements ==

* Kernel with FUSE stuff enabled
* sys-fs/zfs-fuse installed
* '''/etc/init.d/zfs''' started (automatically detects and mounts pools)
* Disk size of 64 Mbytes as a bare minimum (128 Mbytes is the minimum size of a pool). Multiple disk will be simulated through the use of several raw images accessed via the Linux loopback devices.
* At least 512 MB of RAM

== Your first ZFS pool ==

To start with, four raw disks (2 GB each) are created:

<pre>
# for i in 0 1 2 3; do dd if=/dev/zero of=/tmp/zfs-test-disk0${i}.img bs=2G count=1; done
0+1 records in
0+1 records out
2147479552 bytes (2.1 GB) copied, 40.3722 s, 53.2 MB/s
...
</pre>

Then let's see what loopback devices are in use and which is the first free:

<pre>
# losetup -a
# losetup -f
/dev/loop0
</pre>

In the above example nothing is used and the first available loopback device is /dev/loop0. Now associate all of the disks with a loopback device (/tmp/zfs-test-disk00.img -> /dev/loop/0, /tmp/zfs-test-disk01.img -> /dev/loop/1 and so on):

<pre>
# for i in 0 1 2 3; do losetup /dev/loop${i} /tmp/zfs-test-disk0${i}.img; done
# losetup -a
/dev/loop0: [000c]:781455 (/tmp/zfs-test-disk00.img)
/dev/loop1: [000c]:806903 (/tmp/zfs-test-disk01.img)
/dev/loop2: [000c]:807274 (/tmp/zfs-test-disk02.img)
/dev/loop3: [000c]:781298 (/tmp/zfs-test-disk03.img)
</pre>

=== Pool creation ===

It is now time to create our first ZFS data pool and this is accomplished by one of the two commands you have to retain: zfspool. For now, we will ask it to do a simple job: get all of the just created devices and create an aggregated pool:

<pre>
# zfs create myfirstpool /dev/loop0 /dev/loop1 /dev/loop2 /dev/loop3
# mount
...
kstat on /zfs-kstat type fuse (rw,nosuid,nodev,allow_other)
myfirstpool on /myfirstpool type fuse (rw,allow_other,default_permissions)
</pre>

Note that the pool has also been mounted on /myfirstpool! Forget kstat for now, it is mounted automatically by zfs-fuse and countains some performance statistics. Oh by the way, we have used block devices (loopback devices are block devices) to create our ZFS pool, however ZFS can also deal directly with files and the taxonomy used in the ZFS world retains the term '''vdev''' (virtual device). Let's be curious a bit and see what df reports:

<pre>
# df -h
# myfirstpool 7.9G 21K 7.9G 1% /myfirstpool
</pre>

Cool! About 8GB are reported, this is barely the sum of our four ''vdevs'' minus some metadata. What can we do with 8 GB of free storage space? Copy some files in it of course!

=== Some file operations ===

<pre>
# cp -a /usr/src/linux-3.1-rc4 /myfirstpool
# df -h
myfirstpool 7.9G 662M 7.2G 9% /myfirstpool
# cd /myfirstpool
# ls -l /myfirstpool
total 3
drwxrwxr-x 24 root root 56 Aug 29 08:41 linux-3.1-rc4
# ls -l /myfirstpool/linux-3.1-rc4
total 29
-rw-rw-r-- 1 root root 18693 Aug 29 00:16 COPYING
-rw-rw-r-- 1 root root 94790 Aug 29 00:16 CREDITS
drwxrwxr-x 94 root root 222 Aug 29 00:16 Documentation
-rw-rw-r-- 1 root root 2464 Aug 29 00:16 Kbuild
-rw-rw-r-- 1 root root 252 Aug 29 00:16 Kconfig
-rw-rw-r-- 1 root root 200918 Aug 29 00:16 MAINTAINERS
-rw-rw-r-- 1 root root 53537 Aug 29 00:16 Makefile
-rw-r--r-- 1 root root 364907 Aug 29 08:41 Module.symvers
-rw-rw-r-- 1 root root 17459 Aug 29 00:16 README
....
drwxrwxr-x 22 root root 41 Aug 29 08:41 sound
drwxrwxr-x 9 root root 9 Aug 29 00:16 tools
drwxrwxr-x 2 root root 11 Aug 29 08:38 usr
drwxrwxr-x 3 root root 3 Aug 29 00:16 virt
-rwxr-xr-x 1 root root 13126551 Aug 29 08:41 vmlinux
-rw-r--r-- 1 root root 14771911 Aug 29 08:41 vmlinux.o
# make clean
# df -h
Filesystem Size Used Avail Use% Mounted on
...
myfirstpool 7.9G 444M 7.4G 6% /myfirstpool
</pre>

In fact nothing magic, a ZFS pool is acting just like any other existing filesystem :)

=== Unmounting/remounting the pool ===

If ZFS behaves just like any other filesystem, can we unmount it?

<pre>
# umount /myfirstpool
# mount | grep myfirstpool
#
</pre>

No more /myfirstpool in our light of sight. So yes, it is possible to unmount a ZFS pool just like with any other filesystem. But... How can we remount it then? Simple! First check the list of all ZFS pools known by the system:

<pre>
# zpool list
NAME SIZE ALLOC FREE CAP DEDUP HEALTH ALTROOT
myfirstpool 7.94G 444M 7.50G 5% 1.00x ONLINE -
</pre>

Then mount it again:

<pre>
# zpool list
NAME SIZE ALLOC FREE CAP DEDUP HEALTH ALTROOT
myfirstpool 7.94G 444M 7.50G 5% 1.00x ONLINE -
# zfs mount myfirstpool
</pre>

Oh! Did you noticed? We used the '''zfs''' command instead of the '''zpool''' command. You will understand the reason of using '''zfs''' instead of '''zpool''' a bit later, for now just remember that '''zfs''' and zpool are the only two commands used to interact with the ZFS universe. Also note that '''zfs mount...''' is the one and only way to remount a ZFS pool in the VFS arborescence so you can't be confused or do errors.

{{fancynote|The missing leading / ahead of myfirstpool '''is not a typo'''. When a pool is created, ZFS writes in the pool metadata where it must be mounted. Unless overridden, it is assumed that the pool is to be mounted directly under the VFS root in a mountpoint which has the same name of the pool.}}

Let's check what happened:

<pre>
# mount | grep myfirstpool
myfirstpool on /myfirstpool type fuse (rw,allow_other,default_permissions)
# ls -l /myfirstpool
total 3
drwxrwxr-x 23 root root 33 Sep 4 18:18 linux-3.1-rc4
</pre>

Everything is back again!

== ZFS datasets ==

Just like your house is a kind of big container subdivided in many others container (rooms), a ZFS pool can be divided in several logical containers known as ''datasets''. Basically, the role of a dataset is to fullfill the so well known adage ''divide and conquer'' as they define the frontiers where all ZFS operations take place: it is '''only''' possible, for example, to take a snapshot/do a rollback of a dataset '''taken at whole'''.

=== Creating and destroying datasets ===

Creating a dataset in a pool is pretty easy to achieve: you invoke the '''zfs''' command, you give it the name of the pool to divide and the name of the dataset to create. To create three datasets named ''myfirstDS, mysecondDS, mythirdDS'' in ''myfirstpool''(again the missing / ahead of ''myfirstpool'' is '''not''' a typo) :

<pre>
# zfs create myfirstpool/myfirstDS
# zfs create myfirstpool/mysecondDS
# zfs create myfirstpool/mythirdDS
# ls -l /myfirstpool
total 7
drwxrwxr-x 23 root root 33 Sep 4 18:18 linux-3.1-rc4
drwxr-xr-x 2 root root 2 Sep 4 23:34 myfirstDS
drwxr-xr-x 2 root root 2 Sep 4 23:34 mysecondDS
drwxr-xr-x 2 root root 2 Sep 4 23:34 mythirdDS
</pre>

Datasets are appearing just as if they were regular directories. Are they? Try to remove one of those:

<pre>
# rmdir /myfirstpool/myfirstDS
rmdir: failed to remove `/myfirstpool/myfirstDS': Device or resource busy
</pre>

This behavior is absolutely normal, datasets are special entities and must be managed via ZFS commands. Trouble: how a regular directory with files opened by a running process can be distinguished from a ZFS dataset? Both looks similar! Here again, the '''zfs''' command rescues us:

<pre>
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 444M 7.38G 444M /myfirstpool
myfirstpool/myfirstDS 21K 7.38G 21K /myfirstpool/myfirstDS
myfirstpool/mysecondDS 21K 7.38G 21K /myfirstpool/mysecondDS
myfirstpool/mythirdDS 21K 7.38G 21K /myfirstpool/mythirdDS
</pre>

Not obvious but '''zfs list''' also reveals you a great secret: '''we lied you''' in the previous paragraphs. It it not possible to mount a ZFS pool in the VFS arborescence as '''only''' datasets can be mounted. So where is the prank? Our ''myfirstpool'' had been mounted in the VFS and you never defined any datasets in it. How is that possible? Is there some ZFS black magic lying behind? No. When you created the ZFS pool ''myfirstpool'', a special dataset had also been created in the pool automatically for you: the ''root dataset''. When you typed '''zfs mount mypool''', you had in fact interact with this root dataset and not with the pool in itself. The operation was transparent for you and you never noticed its presence although using the zfs command instead of zpool could have given you a hint about what lies under the hood. You see that root dataset in the first line of what zfs list reported in the example above.

So the root dataset (myfirstpool) is mounted on /myfirstpool, myfirstDS is then mounted inside (/myfirstpool/myfirstDS) ditto for mysecondDS and mythirdDS. ''Mounted'' is the exact term because if we have a look at what the '''mount''' command reports we can see that those datasets have been '''''effectively''''' mounted:

<pre>
# mount
rootfs on / type rootfs (rw)
...
myfirstpool on /myfirstpool type fuse (rw,allow_other,default_permissions)
myfirstpool/myfirstDS on /myfirstpool/myfirstDS type fuse (rw,allow_other,default_permissions)
myfirstpool/mysecondDS on /myfirstpool/mysecondDS type fuse (rw,allow_other,default_permissions)
myfirstpool/mythirdDS on /myfirstpool/mythirdDS type fuse (rw,allow_other,default_permissions)
</pre>

As we did before, we can copy some files in the newly created datasets just like they were regular directories:

<pre>
# cp -a /usr/portage /myfirstpool/mythirdDS
# ls -l /myfirstpool/mythirdDS/*
total 438
drwxr-xr-x 45 root root 46 Aug 31 07:37 app-accessibility
drwxr-xr-x 202 root root 203 Sep 2 07:21 app-admin
drwxr-xr-x 3 root root 4 Aug 18 18:13 app-antivirus
drwxr-xr-x 93 root root 94 Aug 18 18:13 app-arch
drwxr-xr-x 38 root root 39 Aug 18 18:13 app-backup
drwxr-xr-x 30 root root 31 Aug 18 18:13 app-benchmarks
drwxr-xr-x 66 root root 67 Aug 18 18:13 app-cdr
drwxr-xr-x 96 root root 97 Aug 18 18:13 app-crypt
drwxr-xr-x 358 root root 359 Aug 18 18:13 app-dicts
...
# df -h | grep DS
myfirstpool/myfirstDS 5.6G 21K 5.6G 1% /myfirstpool/myfirstDS
myfirstpool/mysecondDS 5.6G 21K 5.6G 1% /myfirstpool/mysecondDS
myfirstpool/mythirdDS 7.4G 1.9G 5.6G 25% /myfirstpool/mythirdDS
</pre>

Notice what '''df''' returns: our four datasets shares (don't forget the root dataset!) shares the same storage capacity. Logical indeed: as they are all contained in the same pool they cannot exceed its own storage capacity. Is it possible to cap the maximum capacity of a dataset? Yes, for now just retain that datasets:
# are logical containers where ZFS operations take place
# are concerned at whole by ZFS operations (again: you cannot snapshot/rollback a particular directory located in a dataset, '''you can only operate at the dataset level''')

We have three datasets, but the third is pretty useless and contains a lot of garbage. Is it possible to remove it with a simple '''rm -rf'''? Let's try:

<pre>
# rm -rf /myfirstpool/mythirdDS
rm: cannot remove `/myfirstpool/mythirdDS': Device or resource busy
</pre>

This is perfectly normal, remember that datasets are special entities that requires special care and they are not deletable through regular shell commands. However it is possible to destroy them and here again, the '''zfs''' command comes at our rescue:

<pre>
# zfs destroy myfirstpool/mythirdDS
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 444M 7.38G 444M /myfirstpool
myfirstpool/myfirstDS 21K 7.38G 21K /myfirstpool/myfirstDS
myfirstpool/mysecondDS 21K 7.38G 21K /myfirstpool/mysecondDS
</pre>

''Et voila''! No more third dataset. :)

A bit more subtle case: let's mythirdDS and put another nested one in it then try to destroy mythirdDS again:

<pre>
# zfs create myfirstpool/mythirdDS
# zfs create myfirstpool/mythirdDS/nestedSD
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 444M 7.38G 444M /myfirstpool
myfirstpool/myfirstDS 21K 7.38G 21K /myfirstpool/myfirstDS
myfirstpool/mysecondDS 21K 7.38G 21K /myfirstpool/mysecondDS
myfirstpool/mythirdDS 42K 7.38G 21K /myfirstpool/mythirdDS
myfirstpool/mythirdDS/nestedDS 21K 7.38G 21K /myfirstpool/mythirdDS/nestedDS
# zfs destroy myfirstpool/mythirdDS
cannot destroy 'myfirstpool/mythirdDS': filesystem has children
use '-r' to destroy the following datasets:
myfirstpool/mythirdDS/nestedDS
</pre>

'''zfs''' tells us it has found some others datasets located in ''mythirdDS'' and, thus, is unable to delete it without you consent to make a recursive destruction (-r parameter). Before trying to destroy the dataset again let's create some more nested datasets plus a couple of directories inside ''mythirdDS'':

<pre>
# zfs create myfirstpool/mythirdDS/nestedSD
# zfs create myfirstpool/mythirdDS/nestedSD2
# zfs create myfirstpool/mythirdDS/nestedSD3
# mkdir /myfirstpool/mythirdDS/dir1
# mkdir /myfirstpool/mythirdDS/dir2
# mkdir /myfirstpool/mythirdDS/dir3
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 444M 7.38G 444M /myfirstpool
myfirstpool/myfirstDS 21K 7.38G 21K /myfirstpool/myfirstDS
myfirstpool/mysecondDS 21K 7.38G 21K /myfirstpool/mysecondDS
myfirstpool/mythirdDS 84K 7.38G 21K /myfirstpool/mythirdDS
myfirstpool/mythirdDS/mynestedDS 21K 7.38G 21K /myfirstpool/mythirdDS/mynestedDS
myfirstpool/mythirdDS/mynestedDS2 21K 7.38G 21K /myfirstpool/mythirdDS/mynestedDS2
myfirstpool/mythirdDS/mynestedDS3 21K 7.38G 21K /myfirstpool/mythirdDS/mynestedDS3
# zfs destroy -r myfirstpool/mythirdDS
</pre>

Now what happens if we try to destroy mythird again this time with '-r'?

<pre>
# zfs destroy -r myfirstpool/mythirdDS
cannot destroy 'myfirstpool/mythirdDS/mynestedDS': dataset is busy

</pre>

This is not as exactly normal as it should and seems to be a bug in zfs-fuse, the expected behavior is to automatically unmount any dataset contained inside ''mythirdDS'' then destroy it including ''mythirdDS'' itself. The same kind of operation on a Solaris machine with a similar dataset structure gives:

<pre>
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
....
rpool1/swap 4.04G 23.2G 123M -
testpool/test 55.4K 3.76T 55.4K /testpool/test
testpool/test/ds1 44.9K 3.76T 44.9K /testpool/test/ds1
testpool/test/ds2 44.9K 3.76T 44.9K /testpool/test/ds2
testpool/test/ds3 44.9K 3.76T 44.9K /testpool/test/ds3
testpool/test2 44.9K 3.76T 44.9K /testpool/test2
# mkdir /testpool/test/dir1
# mkdir /testpool/test/dir2
# mkdir /testpool/test/dir1
# zfs destroy -r testpool/test
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
....
rpool1/swap 4.04G 23.2G 123M -
testpool/test2 44.9K 3.76T 44.9K /testpool/test2
</pre>

To go back on ZFS Fuse, just do a few attempts and ''mythirdDS'' should vanish (you may also have to do an explicit '''zfs destroy mythirdDS''' at the end).

=== Snapshotting and rolling back a dataset ===

This is, by far, one of the coolest feature of ZFS: you can litterally take a photograph of a dataset, do whatever you want with the dataset then restore it in the '''exact''' same state just as if nothing had ever happened in the middle. To start with, let's copy some files in ''mysecondDS'':

<pre>
# cp -a /usr/portage /myfirstpool/mysecondDS
# ls /myfirstpool/mysecondDS/portage
total 200
drwxr-xr-x 45 root root 46 Aug 31 07:37 app-accessibility
drwxr-xr-x 202 root root 203 Sep 2 07:21 app-admin
drwxr-xr-x 3 root root 4 Aug 18 18:13 app-antivirus
drwxr-xr-x 93 root root 94 Aug 18 18:13 app-arch
...
drwxr-xr-x 57 root root 58 Aug 22 08:56 x11-wm
drwxr-xr-x 16 root root 17 Aug 18 18:13 xfce-base
drwxr-xr-x 54 root root 55 Aug 18 18:13 xfce-extra
</pre>

Now, let's take a snapshot of ''mysecondDS''. Because we manipulate a dataset and not the pool, we rely on the '''zfs''' command:

<pre>
# zfs snapshot myfirstpool/mysecondDS@Charlie
</pre>

{{fancynote|The syntax is always ''pool/dataset@snapshot-name'', the name of the snapshot is left at your discretion however '''you must use an at sign (@)''' to separate the snapshot name from the rest of the path.}}

After running that command,

<pre>
# ls -la /myfirstpool/mysecondDS
total 9
drwxr-xr-x 3 root root 3 Sep 5 16:49 .
drwxr-xr-x 6 root root 6 Sep 5 15:43 ..
drwxr-xr-x 164 root root 169 Aug 18 18:25 portage
</pre>

You were not thinking you would see something like ''@Charlie'' or ''Charlie'' lying in /myfirstpool/mysecondDS were you? Of course not, this is obvious ;-) Can '''zfs''' be of any help this time? It has rescued us several times in the past:

<pre>
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 2.27G 5.54G 444M /myfirstpool
myfirstpool/myfirstDS 21K 5.54G 21K /myfirstpool/myfirstDS
myfirstpool/mysecondDS 1.84G 5.54G 1.84G /myfirstpool/mysecondDS
#
</pre>

''So where the heck'' is Charlie? And how on earth can we use it if '''*nothing*''' is visible to us. Again the answer is: '''zfs'''! This time we invoke it with the -t parameter set to 'all' meaning "list all dataset '''including snapshots'''":

<pre>
# zfs list
NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 2.27G 5.54G 444M /myfirstpool
myfirstpool/myfirstDS 21K 5.54G 21K /myfirstpool/myfirstDS
myfirstpool/mysecondDS 1.84G 5.54G 1.84G /myfirstpool/mysecondDS
myfirstpool/mysecondDS@Charlie 37K - 1.84G -
#
</pre>

Notice that ''Charlie'' is not mounted and although ''mysecondDS'' holds near 2GB of data, ''Charlie'' takes only a couple of kilobytes in the dataset. This is the consequence of ZFS being a Copy-on-write filesystem, duplicating all of the data blocks is not required. They will be duplicated only when needed: when ZFS sense a change in a data block, it will create a copy of it thus leaving intact the datablock pointed by a snapshot. At the time they are taken, snapshots occupy very little space in the datasets however as the time goes on they tend to "stick"more and more data blocks to be in use. It is wise to delete snapshots when become not needed anymore.

{{fancynote|'''OpenIndiana''' and '''Oracle Solaris''' supports an interesting feature not available in ZFS Fuse: a kind of secret door in the form of a virtual directory named ''.zfs'' (notice the dot ahead). "secret door" because it is really secret! You cannot see it ''even'' with''' ls -la''', however ''.zfs'' is present in just any of your datasets and holds some very interesting clues:

<pre>
# zfs list -t all
...
testpool/test2 205K 3.76T 70.3K /testpool/test2
testpool/test2@snap1 0 - 70.3K -
# cd /testpool/test2
# ls -la
total 22
drwxr-xr-x 11 root root 11 2011-09-05 17:34 .
drwxr-xr-x 6 root root 6 2011-09-05 16:13 ..
drwxr-xr-x 2 root root 2 2011-09-05 17:34 .sometest
drwxr-xr-x 2 root root 2 2011-09-05 17:34 .xyz
drwxr-xr-x 2 root root 2 2011-09-05 16:13 dir1
drwxr-xr-x 2 root root 2 2011-09-05 16:13 dir2
...
# cd /testpool/test2/.zfs
# pwd
/testpool/test2/.zfs
# ls -l
ls -l
total 2
dr-xr-xr-x 2 root root 2 2011-09-05 16:13 shares
dr-xr-xr-x 3 root root 3 2011-09-05 17:19 snapshot
# cd snapshot
# ls -l
total 2
drwxr-xr-x 9 root root 9 2011-09-05 17:19 snap1
# cd snap1
# ls -l
total 22
drwxr-xr-x 11 root root 11 2011-09-05 17:34 .
drwxr-xr-x 6 root root 6 2011-09-05 16:13 ..
drwxr-xr-x 2 root root 2 2011-09-05 17:34 .sometest
drwxr-xr-x 2 root root 2 2011-09-05 17:34 .xyz
drwxr-xr-x 2 root root 2 2011-09-05 16:13 dir1
drwxr-xr-x 2 root root 2 2011-09-05 16:13 dir2
...
</pre>

Despite you cannot change the snapshot contents, you can access it without having to roll it back to examine its contents. Extremely nifty design choice from the ZFS designers!
}}

Now we have found Charlie, let's do some changes in the ''mysecondDS'':

<pre>
# rm -rf /myfirstpool/mysecondDS/portage
# echo "Hello, world" > /myfirstpool/mysecondDS/hello.txt
# ls -l /myfirstpool/mysecondDS
total 1
-rw-r--r-- 1 root root 13 Sep 5 18:07 hello.txt
# cat /myfirstpool/mysecondDS/hello.txt
Hello, world
</pre>

Whooops...removing portage was not the best idea to have and we do not bother about hello.txt. We will have to move back at checkpoint Charlie!

<pre>
# zfs rollback myfirstpool/mysecondDS@Charlie
# ls -l /myfirstpool/mysecondDS
total 6
drwxr-xr-x 164 root root 169 Aug 18 18:25 portage
</pre>

Again, ZFS handled everything for you and you now have the contents of ''mysecondDS'' exactly as it was at the time the snapshot ''Charlie'' was taken. Not more complicated than that. Hang on you hat, we have not finished.

=== Dealing with several snapshots (time-traveling machine) ===

So far we only used a single snapshot just to keep things simple. However a dataset can hold several snapshots and moreover you can do a delta between two snapshots and nothing is really much more complicated than you have seen so far.

Let's consider myfirstDS this time. This dataset should be empty as we did nothing in it so far:

<pre>
# ls -la /myfirstpool/myfirstDS
total 3
drwxr-xr-x 2 root root 2 Sep 4 23:34 .
drwxr-xr-x 6 root root 6 Sep 5 15:43 ..
</pre>

Now generate some contents, take a snapshot (snapshot-1), add more content, take a snapshot again (snapshot-2), do some more modifications and take a third snapshot (snapshot-3):

<pre>
# echo "Hello, world" > /myfirstpool/myfirstDS/hello.txt
# cp /usr/src/linux-3.1-rc4.tar.bz2 /myfirstpool/myfirstDS
# ls -l /myfirstpool/myfirstDS
# ls -l /myfirstpool/myfirstDS
total 75580
-rw-r--r-- 1 root root 13 Sep 5 22:38 hello.txt
-rw-r--r-- 1 root root 77220912 Sep 5 22:38 linux-3.1-rc4.tar.bz2
# zfs snapshot myfirstpool/myfirstDS@snapshot-1
# echo "Goodbye, world" > /myfirstpool/myfirstDS/goodbye.txt
# echo "Are you there?" >> /myfirstpool/myfirstDS/hello.txt
# cp /usr/src/linux-3.0.tar.bz2 /myfirstpool/myfirstDS
# rm /myfirstpool/myfirstDS/linux-3.1-rc4.tar.bz2
# zfs snapshot myfirstpool/myfirstDS@snapshot-2
# echo "Still there?" >> /myfirstpool/myfirstDS/goodbye.txt
# rm /myfirstpool/myfirstDS/hello.txt
# cp /proc/config.gz /myfirstpool/myfirstDS
# zfs snapshot myfirstpool/myfirstDS@snapshot-3
# zfs list -t all
# zfs list -t all
NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 2.41G 5.40G 444M /myfirstpool
myfirstpool/myfirstDS 147M 5.40G 73.3M /myfirstpool/myfirstDS
myfirstpool/myfirstDS@snapshot-1 73.8M - 73.8M -
myfirstpool/myfirstDS@snapshot-2 20K - 73.3M -
myfirstpool/myfirstDS@snapshot-3 0 - 73.3M -
</pre>

Wow, nice demonstration on how a Copy-on-Write filesystem like ZFS works: what do we observe? First it is quite obvious to see that ''snapshot-1'' is quite big. Is is possible that having a so big snapshot to be the consequence of removing /myfirstDS/linux-3.1-rc4.tar.bz2? Absolutely. Remember that a snapshot is a photograph of what a dataset contains at a given time, deleted information and unmodified original information is retained by the snapshot even you delete it from the dataset or bring in some changes to it. If you look again at the command history between snapshot-2 and snapshot-3, you will notice that we removed a small file and changed another small file a bit thus having a little information delta between what the dataset content at this time and what it also actually contains leading to a very small snapshot at the end. The third dataset is the exact copy of what the current dataset contains thus its size is very close to zero (truncated to zero on what you see).

$100 question: "How can I see what changed between snapshots?". Answer: ''yes, you can!'' Nuance is: ZFS Fuse does not support it yet :( Nevertheless here is what snapshots diffing looks like on an OpenIndiana/Solaris machine:

<pre>
# zfs create testpool/test2
# cd /testpool/test2
# wget http://www.kernel.org/pub/linux/kernel/v3.0/testing/patch-3.1-rc4.bz2
# echo "Hello,world" > hello.txt
# zfs snapshot testpool/test2@s1

# rm patch-3.1-rc4.bz2
# echo 'Goodbye!' > goodbye.txt
# echo 'Still there?' >> hello.txt
# zfs snapshot testpool/test2@s2

# echo 'Hello, again' >> hello.txt
# ln -s goodbye.txt goodbye2.txt
# mv hello.txt hello-new.txt
# zfs snapshot testpool/test2@s3

# zfs list -t all | grep test2
testpool/test2 8.49M 3.76T 47.9K /testpool/test2
testpool/test2@s1 8.41M - 8.42M -
testpool/test2@s2 29.2K - 46.4K -
testpool/test2@s3 0 - 47.9K -

# zfs diff testpool/test2@s1 testpool/test2@s2
M /testpool/test2/
- /testpool/test2/patch-3.1-rc4.bz2
M /testpool/test2/hello.txt
+ /testpool/test2/goodbye.txt

# zfs diff testpool/test2@s2 testpool/test2@s3
M /testpool/test2/
R /testpool/test2/hello.txt -> /testpool/test2/hello-new.txt
+ /testpool/test2/goodbye2.txt

# zfs diff testpool/test2@s1 testpool/test2@s3
M /testpool/test2/
- /testpool/test2/patch-3.1-rc4.bz2
R /testpool/test2/hello.txt -> /testpool/test2/hello-new.txt
+ /testpool/test2/goodbye.txt
+ /testpool/test2/goodbye2.txt

# zfs diff testpool/test2@s3 san/test2@s1
Unable to obtain diffs:
Not an earlier snapshot from the same fs
</pre>

Where M,R,+,- stands for:

* M: item has been modified
* R: item has been renamed
* +: item has been added
* -: item has been removed

Observe the output of each diff and draw you own conclusion on what we did at each step and what appears in the diff. It is not possible to get a detailed diff similar to what Git and others gives but you have the big picture of what changed between snapshots.

If ZFS-Fuse does not implements (yet) a snapshot diffing capability, it can deal with several snapshots and is able to jump across several steps backwards. Suppose we want ''myfirstDS'' to go back exactly is was when we took the dataset photograph named ''snapshot-1'':

<pre>
# zfs rollback myfirstpool/myfirstDS@snapshot-1
cannot rollback to 'myfirstpool/myfirstDS@snapshot-1': more recent snapshots exist
use '-r' to force deletion of the following snapshots:
myfirstpool/myfirstDS@snapshot-3
myfirstpool/myfirstDS@snapshot-2
</pre>

This is not a bug, this is absolutely normal. The '''zfs''' command asks you to give it the explicit permission to remove the two others snapshots as they becomes useless (restoring them would be an absolute no sense) once snapshot-1 is restored. Second attempt:

<pre>
# zfs rollback myfirstpool/myfirstDS@snapshot-1
# ls -l /myfirstpool/myfirstDS
total 75580
-rw-r--r-- 1 root root 13 Sep 5 22:38 hello.txt
-rw-r--r-- 1 root root 77220912 Sep 5 22:38 linux-3.1-rc4.tar.bz2
# zfs list -t all

NAME USED AVAIL REFER MOUNTPOINT
myfirstpool 2.34G 5.47G 444M /myfirstpool
myfirstpool/myfirstDS 73.8M 5.47G 73.8M /myfirstpool/myfirstDS
myfirstpool/myfirstDS@snapshot-1 0 - 73.8M -
myfirstpool/mysecondDS 1.84G 5.47G 1.84G /myfirstpool/mysecondDS
myfirstpool/mysecondDS@snapshot1 37K - 1.84G -
</pre>

''myfirstDS'' effectively returned to its state when ''snapshot-2'' was taken and the snapshots ''snapshot-2'' and ''snapshot-3'' vanished.

{{fancynote|You can leap several steps backward at the cost of '''loosing''' your subsequent modifications forever. }}

=== Streaming datasets over the network ===

{{fancyimportant|'''Nothing in an infrastructure is as much critical as having reliable backups of the data''' used by an organization. Whereas a server can be remounted from scratch, the data it contains is very likely to be lost '''forever''' whenever a disaster occurs. Of course, as the data is the blood of an organization business processes, its '''integrity''' and '''confidentiality''' must be preserved in all cases. }}

You find ZFS snaphots useful? Well, you have seen just a small part of their potential. As a snapshot is a photograph of what a dataset contains frozen in the time, snapshots can be seen as being no more than a data backup. Like any backup, they must not stay on the local machine but must be put elsewhere and the common good sense tells to keep backups in a safe place, making them travel through a secure channel. By "secure channel" we intend something like a trusted person in your organization whose job consists of bringing a box of tapes off-site in a secure location but we also intend a secure communication channel like an SSH tunnel over two hosts without any human intervention.

ZSH designers had the same vision and made possible for a dataset to be able to be sent over a network. How is that possible? Simple: the process involves two peers who can use through a communication channel like the one established by '''netcat''' (OpenSSH supports a similar functionality but with an encrypted communication channel). For the sake of the demonstration, we will use two Solaris boxes at each end-point.

How stream some ZFS bits over the network? Here again, '''zfs''' is the answer. A nifty move from the designers was to use ''stdin'' and ''stdout'' as transmission/reception channels thus allowing great a flexibility in processing the ZFS stream. You can envisage, for instance, to compress your stream then crypt it then encode it in base64 then sign it and so on. It sounds a bit overkill but it is possible and in the general case you can use any tool that swallow the data from ''stdin'' and spit it through ''stdout'' in your plumbing.

{{fancynote|The rest of this section has been done entirely on two Solaris 11 machines.}}

1. Sender side:

<pre>
# zfs create testpool2/zfsstreamtest
# echo 'Hello, world!' > /testpool2/zfsstreamtest/hello.txt
# echo 'Goodbye, world' > /testpool2/zfsstreamtest/goodbye.txt
# zfs snapshot zfs testpool2/zfsstreamtest@s1
# zfs list -t snapshot
NAME USED AVAIL REFER MOUNTPOINT
testpool2/zfsstreamtest@s1 0 - 32K -
</pre>

2. Receiver side (the dataset ''zfs-stream-test'' will be created and should not be present):
<pre>
# nc -l -p 7000 | zfs receive testpool/zfs-stream-test
</pre>

At this point the receiver is waiting after some data.

3. Sender side:
<pre>
# zfs send testpool2/zfsstreamtest@s1 | nc 192.168.aaa.bbb.ccc 7000
</pre>

4. Receiver side:
<pre>
# zfs list -t snapshot
NAME USED AVAIL REFER
...
testpool2/zfs-stream-test@s1 0 - 46.4K -
</pre>

Note that we did not set an explicit snapshot name the the second step but it could have been possible to choose anything else but the default which is the name of the snapshot sent over the network. In that case the dataset which will contain the snapshot needs to be created first:
<pre>
# nc -l -p 7000 | zfs receive testpool/zfs-stream-test@mysnapshot01
</pre>

Once received you would get:

<pre>
# zfs list -t snapshot
NAME USED AVAIL REFER
...
testpool2/zfs-stream-test@mysnapshot01 0 - 46.4K -
</pre>

5. Just for the sake of the curiosity let's do a rollback on the receiver side:

<pre>
# zfs rollback testpool2/zfsstreamtest@s1
# ls -l /testpool2/zfs-stream-test
total 2
-rw-r--r-- 1 root root 15 2011-09-06 23:54 goodbye.txt
-rw-r--r-- 1 root root 13 2011-09-06 23:53 hello.txt
# cat /testpool2/zfs-stream-test/hello.txt
Hello, world
</pre>

Because ZFS streaming operates using the starnd input and output (''stdin'' / ''stdout'') you can build a bit more complex pipeline like:

<pre>
# zfs send testpool2/zfsstreamtest@s1 | gzip | nc 192.168.aaa.bbb.ccc 7000
</pre>

The above example was using two hosts but a simpler setup is also possible: you are not required to send you data over the network with '''netcat''', you can store it to a regular file then mail it or store it on a USB key. By the way: we have not finished! We took only a simple case here: it is absolutely possible to do the exact same operation with the difference between snapshots (incremental). Just like an incremental backup takes only what has changed, ZFS can determine the difference between two snapshots and streaming instead of streaming a snapshot taken at whole. Although ZFS can detect and act on differentials, it does not operate (yet) at the block level: if only a few bytes of a very big file have changed, the whole file will be taken into consideration (operating at data block level is possible with some tools like the well-known '''rsync''').

Consider the following:

* A dataset snapshot (S1) contains two files:
** A -> 10 MB
** B -> 4 GB
* A bit later some files (named C, D and E) are added to the dataset and another snapshot is (S2) taken. S2 contains:
** A -> 10 MB
** B -> 4 GB
** C -> 3 MB
** D -> 500 KB
** E -> 1GB

With a full transfer of S2 A,B,C,D and E would be streamed whereas an incremental transfert (S2-S1), zfs would only process C, D and E. The next $100 question:''"How can we stream a difference of snapshot? '''zfs''' again?"'' Yes! This time with a subtle difference: a special option specified on the command line telling it must use a difference rather than a full snapshot. Assuming a few more files are added in ''testpool2/zfsstreamtest'' dataset and a snapshot (s2) is has been taken, the delta between s2 and s1 (s2-s1) giving s3 can be send like this (on the receiver side the same as shown above is used, nothing special is required alos notice the presence of the -i option):

* Sender:
<pre>
# zfs send -i testpool2/zfsstreamtest@s1 testpool2/zfsstreamtest@s2 | nc 192.168.aaa.bbb.ccc 7000
</pre>

* Receiver:
<pre>
# nc -l -p 7000 | zfs receive testpool/zfs-stream-test
# zfs list -t snapshot
testpool/zfs-stream-test@s1 28.4K - 46.4K -
testpool/zfs-stream-test@s2 0 - 47.1K -
</pre>

Note that although we did not specified any snapshot name to use on the receiver side, ZFS used by default the name of the second snapshot involved in the delta (''s2'' here).

$200 question: suppose we delete all of the received snapshots so far on the receiver side and we try to send the difference between s2 and s1, what would happen? ZFS will protest on the receiver side although no error message will be visible on the sender side:
<pre>
cannot receive incremental stream: destination testpool/zfs-stream-test has been modified
since most recent snapshot
</pre>

It is even worse if we remove the dataset used to receive the data:

<pre>
cannot receive incremental stream: destination 'testpool/zfs-stream-test' does not exist
</pre>

{{fancyimportant|ZFS streaming over a network has '''no underlying protocol''', therefore the sender just assumes the data has been successfully received and processed. It '''does not care''' whether a processing error occurs.}}

=== Govern a dataset by attributes ===

So far, most of a filesystem capabilities were driven by separate and scarced command line line tools (e.g. tune2fs, edquota, rquota, quotacheck...) which all have their own ways to handle tasks and can go through tricky ways sometimes especially the quota-related management utilities. Moreover, there was no easy way to handle a limitations on a directory rather than putting it a a dedicated partition or logical volume implying downtimes when additional space was to be added. Quota management is however one of the many facets disk space management includes.

In the ZFS world, many aspects are now managed by simply setting/clearing a property attached to a ZFS dataset through the now so well-known command '''zfs'''.You can, for example:

* put a size limit on a dataset
* reserve a space for dataset (that space is ''guaranteed'' to be available in the future although not being allocated at the time the reservation is made)
* control if new files are encrypted and/or compressed
* define a quota per user or group of users
* control checksum usage => '''never turn that property off unless having very good reasons you are likely to never have''' (no checksums = no silent data corruption detection)
* share a dataset by NFS/CIFS
* control automatic data deduplication

Not all of a dataset properties are settable, some of them are set and managed by the operating system in the background for you and thus cannot be modified.

{{fancynote|Solaris/OpenIndiana users: ZFS has a tight integration with the NFS/CIFS server, thus it is possible to share a zfs dataset by setting adequate attributes. ZFS on Linux (native kernel mode port) also has a tight integration with the built-in Linux NFS server, the same for ZFS fuse although still experimental. Under FreeBSD ZFS integration has been done both with NFS and Samba (CIFS).}}

Like any other action concerning datasets, properties are sets and unset via the zfs command. On our Funtoo box running zfs-Fuse we can, for example, start by seeing the value of all properties for the dataset ''myfirstpool/myfirstDS'':

<pre>
# zfs get all myfirstpool/myfirstDS
zfs get all myfirstpool/myfirstDS
NAME PROPERTY VALUE SOURCE
myfirstpool/myfirstDS type filesystem -
myfirstpool/myfirstDS creation Sun Sep 4 23:34 2011 -
myfirstpool/myfirstDS used 73.8M -
myfirstpool/myfirstDS available 5.47G -
myfirstpool/myfirstDS referenced 73.8M -
myfirstpool/myfirstDS compressratio 1.00x -
myfirstpool/myfirstDS mounted yes -
myfirstpool/myfirstDS quota none default
myfirstpool/myfirstDS reservation none default
myfirstpool/myfirstDS recordsize 128K default
myfirstpool/myfirstDS mountpoint /myfirstpool/myfirstDS default
myfirstpool/myfirstDS sharenfs off default
myfirstpool/myfirstDS checksum on default
myfirstpool/myfirstDS compression off default
myfirstpool/myfirstDS atime on default
myfirstpool/myfirstDS devices on default
myfirstpool/myfirstDS exec on default
myfirstpool/myfirstDS setuid on default
myfirstpool/myfirstDS readonly off default
myfirstpool/myfirstDS zoned off default
myfirstpool/myfirstDS snapdir hidden default
myfirstpool/myfirstDS aclmode groupmask default
myfirstpool/myfirstDS aclinherit restricted default
myfirstpool/myfirstDS canmount on default
myfirstpool/myfirstDS xattr on default
myfirstpool/myfirstDS copies 1 default
myfirstpool/myfirstDS version 4 -
myfirstpool/myfirstDS utf8only off -
myfirstpool/myfirstDS normalization none -
myfirstpool/myfirstDS casesensitivity sensitive -
myfirstpool/myfirstDS vscan off default
myfirstpool/myfirstDS nbmand off default
myfirstpool/myfirstDS sharesmb off default
myfirstpool/myfirstDS refquota none default
myfirstpool/myfirstDS refreservation none default
myfirstpool/myfirstDS primarycache all default
myfirstpool/myfirstDS secondarycache all default
myfirstpool/myfirstDS usedbysnapshots 18K -
myfirstpool/myfirstDS usedbydataset 73.8M -
myfirstpool/myfirstDS usedbychildren 0 -
myfirstpool/myfirstDS usedbyrefreservation 0 -
myfirstpool/myfirstDS logbias latency default
myfirstpool/myfirstDS dedup off default
myfirstpool/myfirstDS mlslabel off -
</pre>

How can we set a limit that prevents ''myfirstpool/myfirstDS'' to not use more than 1 GB of space in the pool? Simple, just set the ''quota'' property:

<pre>
# zfs set quota=1G myfirstpool/myfirstDS
# zfs get quota myfirstpool/myfirstDS
NAME PROPERTY VALUE SOURCE
myfirstpool/myfirstDS quota 1G local
</pre>

May be something poked your curiosity: ''what "SOURCE" means?'' "SOURCE" describes how the property has been determined for the dataset and can have several values:
* '''local''': the property has been explicitly set for this dataset
* '''default''': a default value has been assigned by the operating system if not explicitely set by the system adminsitrator (e.g SUID allowed or not in the above example).
* '''dash (-)''': not modifiable intrinsic property (e.g. dataset creation time, whether the dataset is currently mounted or not, dataset space usage in the pool, average compression ratio...)

Before copying some files in the dataset, let's fix a binary (on/off) property:
<pre>
# zfs set compression=on myfirstpool/myfirstDS
</pre>

Now try to put more than 1GB of data in the dataset:

<pre>
# dd if=/dev/zero of=/myfirstpool/myfirstDS/one-GB-test bs=2G count=1
dd: writing `/myfirstpool/myfirstDS/one-GB-test': Disk quota exceeded
</pre>

=== Permission delegation ===

ZFS brings a feature known as delegated administration. Delegated administration enables ordinary users to handle administrative tasks on a dataset without being administrators. '''It is however not a sudo replacement as it covers only ZFS related tasks''' such as sharing/unsharing, disk quota management and so on. Permission delegation shines in flexibility because such delegation can be handled by inheritance though nested datasets. Pewrmission deleguation is handled via '''zfs''' through its '''allow''' and '''disallow''' options.

= Data redundancy with ZFS =

Nothing is perfect and the storage medium (even in datacenter-class equipment) is prone to failures and fails on a regular basis. Having data redundancy is mandatory to help in preventing single-points of failure (SPoF). Over the past decades, RAID technologies were powerful however their power is precisely their weakness: as operating at the block level, they do not care about what is stored on the data blocks and have no ways to interact with the filesystems stored on them to ensure data integrity is properly handled.

== Some statistics ==

It is not a secret to tell that a general trend in the IT industry is the exponential growth of data quantities. Just thinking about the amount of data Youtube, Google or Facebook generates every day taking the case of the first [http://www.website-monitoring.com/blog/2010/05/17/youtube-facts-and-figures-history-statistics some statistics] gives:
* 24 hours of video is generated every ''minute'' in March 2010 (May 2009 - 20h / October 2008 - 15h / May 2008 - 13h)
* More than 2 ''billions'' views a day
* More video is produced on Youtube every 60 days than 3 major US broadcasting networks did in the last 60 years

Facebook is also impressive (Facebook own stats):

* over 900 million objects that people interact with (pages, groups, events and community pages)
* Average user creates 90 pieces of content each month (750 millions users active)
* More than 2.5 million websites have integrated with Facebook

What is true with Facebook and Youtube is also true with many other cases (think one minutes about the amount of data stored in iTunes) especially with the growing popularity of cloud computing infrastructures. Despite the progress of the technology a "bottleneck" still exists: the storage reliability is nearly the same over the years. If only one organization in the world generate huge quantities of data it would be the [http://public.web.cern.ch CERN] (''Conseil Européen pour la Recherche Nucléaire'', now officially known as ''European Organization for Nuclear Research'') as their experiments can generate spikes of many terabytes of data within a few seconds. A study done in 2007 quoted by a [http://www.zdnet.com/blog/storage/data-corruption-is-worse-than-you-know/191 ZDNet article] reveals that:

* Even ECC memory cannot be always be helpful: 3 double-bit errors (uncorrectable) occurred in 3 months on 1300 nodes. Bad news: it should be '''zero'''.
* RAID systems cannot protect in all cases: monitoring 492 RAID controller for 4 weeks showed an average error rate of 1 per ~10^14 bits, giving roughly 300 errors for every 2.4 petabytes
* Magnetic storage is still not reliable even on high-end datacenter class drives: 500 errors found over 100 nodes while writing 2 GB file to 3000+ nodes every 2 hours then read it again and again for 5 weeks.

Overall this means: 22 corrupted files (1 in every 1500 files) for a grand total of 33700 files holding 8.7TB of data. And this study is 5 years old....

== Source of silent data corruption ==

http://www.zdnet.com/blog/storage/50-ways-to-lose-your-data/168

Not an exhaustive list but we can quote:

* Cheap controller or buggy driver that does not reports errors/pre-failure conditions to the operating system;
* "bit-leaking": an harddrive consists of many concentric magnetic tracks. When the hard drive magnetic head writes bits on the magnetic surface it generates a very weak magnetic field however sufficient to "leak" on the next track and change some bits. Drives can generally, compensate those situations because they also records some error correction data on the magnetic surface
* magnetic surface defects (weak sectors)
* Hard drives firmware bugs
* Cosmic rays hitting your RAM chips or hard drives cache memory/electronics
*

== Building a mirrored pool ==

== ZFS RAID-Z ==

=== ZFS/RAID-Z vs RAID-5 ===

RAID-5 is very commonly used nowadays because of its simplicity, efficiency and fault-tolerance. Although the technology did its proof over decades, it has a major drawback known as "The RAID-5 write hole". if you are familiar with RAID-5 you already know that is consists of spreading the stripes across all of the disks within the array and interleaving them with a special stripe called the parity. Several schemes of spreading stripes/parity between disks exists in the natures, each one with its own pros and cons, however the "standard" one (also known as ''left-asynchronous'') is:

<pre>
Disk_0 | Disk_1 | Disk_2 | Disk_3
[D0_S0] | [D0_S1] | [D0_S2] | [D0_P]
[D1_S0] | [D1_S1] | [D1_P] | [D1_S2]
[D2_S0] | [D2_P] | [D2_S1] | [D2_S2]
[D2_P] | [D2_S0] | [D2_S1] | [D2_S2]
</pre>

The parity is simply computed by XORing the stripes of the same "row", thus giving the general equation:
* [Dn_S0] XOR [Dn_S1] XOR ... XOR [Dn_Sm] XOR [Dn_P] = 0
This equation can be rewritten in several ways:
* [Dn_S0] XOR [Dn_S1] XOR ... XOR [Dn_Sm] = [Dn_P]
* [Dn_S1] XOR [Dn_S2] XOR ... XOR [Dn_Sm] XOR [Dn_P] = [Dn_S0]
* [Dn_S0] XOR [Dn_S2] XOR ... XOR [Dn_Sm] XOR [Dn_P] = [Dn_S1]
* ...and so on!

Because the equations are a combinations of exclusive-or, it is possible to easily compute a parameter if it is missing. Let say we have 3 stripes plus one parity composed of 4 bits each but one of them is missing due to a disk failure:

* D0_S0 = 1011
* D0_S1 = 0010
* D0_S2 = <missing>
* D0_P = 0110

However we know that:
* D0_S0 XOR D0_S1 XOR D0_S2 XOR D0_P = 0000 also rewritten as:
* D0_S2 = D0_S1 XOR D0_S2 XOR D0_P

Applying boolean algebra it gives:''' D0_S2 = 1011 XOR 0010 XOR 0110 = 1111'''.
Proof: '''1011 XOR 0010 XOR 1111 = 0110''' this is the same as '''D0_P'''

''''''So what's the deal?''''''
Okay now the funny part, forgot the above hypothesis and imagine we have this:

* D0_S0 = 1011
* D0_S1 = 0010
* D0_S2 = 1101
* D0_P = 0110

Applying boolean algebra magics gives 1011 XOR 0010 XOR 1101 => 0100. Problem: this is different of D0_P (0110). Can you tell which one (or which ONES) of the four terms lies? If you find a mathematically acceptable solution, found your company because you have just solved a big computer science problem. If humans can't solve the question, imagine how hard it is for the poor little RAID-5 controller to determine which stripe is right and which one lies and the resulting "datageddon" (i.e. massive data corruption on the RAID-5 array) when the RAID-5 controller detect error and start to rebuild the array.

This is not science fiction, this a pure reality and the weakness stays in the RAID-5 simplicity. Here is how it can happen: an urban legend with RAID-5 arrays is that they update stripes in an atomic transaction (all of the stripes+parity are written or none of them). Too bad, this is just not true, the data is written on the fly and if for a reason or another the machine where the RAID-5 array has a power outage or crash, the RAID-5 controller will simply have no idea about what he was doing and which stripes are up to date which ones are not up to date. Of course, RAID controllers in servers do have a replaceable on-board battery and most of the time the server they reside in is connected to an auxiliary source like a battery-based UPS or a diesel/gas electricity generator. However, Murphy laws or unpredictable hazards can, sometimes, happens....

Another funny scenario: imagine a machine with a RAID-5 array (on UPS this time) but with non ECC memory. the RAID-5 controller splits the data buffer in stripes, computes a data stripe and starts to write them on the different disks of the array. But...but...but... For some odd reason, only one bit in one of the stripes flips (cosmic rays, RFI...) after the parity calculation. Too bad too sad, one of the written stripes contains corrupted data and it is silently written on the array. Datageddon in sight!

Not to make you freaking: storage units have sophisticated error correction capability (a magnetic surface or an optical recording surface is not perfect and reading/writing error occurs) masking most the cases. However, some established statistics estimates that even with error correction mechanism one bit over 10^16 bits transferred is incorrect. 10^16 is really huge but unfortunately in this beginning of the XXIst century with datacenters brewing massive amounts of data with several hundreds to not say thousands servers this this number starts to give headaches: '''a big datacenter can face to silent data corruption every 15 minutes''' (Wikepedia). No typo here, a potential disaster may silently appear 5 times an hour for every single day of the year. Detection techniques exists but traditional RAID-5 arrays in them selves can be a problem. Ironic for a so popular and widely used solution :)

If RAID-5 was an acceptable trade-off in the past decades, it simply made its time. RAID-5 is dead? '''*Horray!*'''

= More advanced topics =

== ZFS Intention Log (ZIL) ==

= Final words and lessons learned =

ZFS surpasses by far (as of September 2011) every of the well-known filesystems around there: none of them propose such an integration of features and certainly not with this management simplicity and robustness. However in the Linux world it is definitely a no-go in the short term especially for production systems. The two known implementations are not ready for production environments and lacks some important features or behave in a clunky manner, this is absolutely correct as none of them pretend to be at this level of maturity and the licensing incompatibility between the code opened by Sun Microsystems some years ago and the GNU/GPL does not help the cause. However, both look '''very promising''' once their corners will become rounded.

For a Linux system, the nearest plan B is you seek for a BTRFS like filesystem covering some of the functionalities offered by ZFS is BTRFS (still considered as experimental, be prepared to a disaster sooner or later although BTRFS is used by some Funtoo core team members since 2 years and proved to be quite stable in practise). BTRFS however does not pushes the limits as much as ZFS does: it does not have built-in snapshot differentiation tool nor implement built-in filesystem streaming capabilities and roll-backing a BTRFS subvolume is a bit more manual than in ''"the ZFS way of life"''.

= Footnotes & references =
Source: [http://docs.huihoo.com/opensolaris/solaris-zfs-administration-guide/html/index.html solaris-zfs-administration-guide]
[[Category:Labs]]
[[Category:Articles]]
[[Category:Filesystems]]

Funtoo Linux Installation on ARM

2013-01-12T16:13:31Z

Palica: /* Choosing a root password (alternative) */

Funtoo now provides [http://ftp.osuosl.org/pub/funtoo/funtoo-current/arm-32bit/ stage3 images] for arm platform. At this time are only armv6j_hardfp and armv7a_hardfp stages available. If you would like us to support other processors (see the list below), please fill a bug report on [http://bugs.funtoo.org].

== List of ARM processor "flavors" ==
* armv4l-unknown-linux-gnu (Rebel NetWinder, HP Armada and other devices having an ARMv4 processor, which is only capable of running the old ABI. Nevertheless it should work on newer CPUs)
* armv4tl-softfloat-linux-gnueabi (OpenMoko FreeRunner and other devices using an ARMv4T processor. Uses the new ARM EABI and software floating point by default)
* armv5tel-softfloat-linux-gnueabi (almost all ARM NAS, devices based on the Marvell Orion and Marvell Kirkwood, Marvell Sheevaplug, Marvell OpenRD, Guruplug, Dreamplug, QNAP TS109/TS209/TS409/TS119/TS219/TS419, Buffalo Linkstation/Kurobox PRO, HP mv2120, HP iPAQ, Linksys NSLU2 and other devices using an ARMv5TE processor. Uses the new ARM EABI and software floating point by default)
* armv6j-unknown-linux-gnueabi ([[Raspberry Pi]], Nokia N800/N810, Smart Q7, OMAP2-based devices and other multimedia devices using an ARMv6 CPU and VFP. Uses the new ARM EABI and hardware floating point by default)
* armv7a-unknown-linux-gnueabi (OMAP3-based devices(Beagleboard, IGEPv2, Devkit8000, AlwaysInnovating Touchbook, [[Nokia N900]]), OMAP4-based devices([[Pandaboard]]), Freescale i.MX515-based devices([[Efika MX]], Babbage Board, Lange Board…) Marvell Dove/Armada, Nvidia Tegra2-based devices(Toshiba AC100, Toshiba Folio), ST-Ericsson NOVA A9500-based devices(Snowball), Exynos 4412 ([[Odroid-X]], Odroid-Q) and other devices using an ARMv7-A processor. Uses the new ARM EABI and generic(not NEON) hardware floating point by default
* armv7a-hardfloat-linux-gnueabi (The same as armv7a-unknown-linux-gnueabi, but this one uses hardfloat instead of softfp. Read more about it here: http://wiki.debian.org/ArmHardFloatPort)

== Default installation of Funtoo on your platform/board ==
This document is not a complete installation tutorial. Basic information about Funtoo Linux installation can be found on [[Funtoo Linux Installation]]. The goal of this document is to provide general information about installing Funtoo Linux on an ARM device, and highlight differences with a x86 installation.

The following notes are non-board specific. Other instructions can be found in the specific articles for the above mentioned devices.

=== Overview ===
Most of the ARM boards come with a SD card slot, so you will need an empty SD card (4GB is enough to get you started), in most cases the boards are also equipped with debug port which can be used with USB-to-serial cables, if you have one, you can use it to login to the machine without the need of connecting keyboards or displays. You will need a network connection to be able to download stages, kernel and update your portage tree.

=== Kernel and bootloader setup ===
Before you start you will need a kernel and a bootloader for your device. Some of the devices look for bootloader (in most cases U-Boot) on the SD along with the kernel.

More information about the kernel and bootloader can be found on pages specific for your device.

=== Installing Funtoo (overview) ===

The installation on these devices differs from the normal installation procedure of booting an installation environment and chrooting from there to your new root, and can be little bit easier, but in some cases tricky.

Overview of the installation:
* Extract stage3 to the 2nd partition of the SD card
* Extract portage snapshot
* Setup fstab
* Setup root password
* Configure hostname and networking (optional, but recommended)
* Enable SSH access (optional, but recommended)
* Enable serial console access (optional, but recommended)
* Correct RTC "bug" with swclock

==== Installing the Stage 3 tarball ====

ARM stage3 tarballs can be found on [http://ftp.osuosl.org/pub/funtoo/funtoo-current/arm-32bit/]. Use the subarchitecture that suits best your device.

Mount the partition that will hold your rootfs of the SD card and extract the stage3 you have downloaded.

<console>
# ##i##mkdir /mnt/SD_root
# ##i##mount /dev/sdcard-device-px /mnt/SD_root
</console>

Extract the stage3 (it may take a while).
<console>
# ##i##tar xapf stage3-armv7a_hardfp-xxxx.tar.xz -C /mnt/SD_root
</console>

==== Extracting a portage snapshot ====

Now, download the portage snapshot from [http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/], and extract it to your partition.

<console>
# ##i##tar xapf portage-latest.tar.xz -C /mnt/SD_root/usr
</console>

==== Setup fstab ====
Edit the /mnt/SD_root/etc/fstab file to look like this:

<pre>
/dev/mmcblk0p1 /boot vfat noauto,noatime 1 2
/dev/mmcblk0p2 / ext4 noatime 0 1
</pre>

Adjust the partition devices and types to suit your needs.

==== Setting the default root password ====

{{fancywarning|Don't skip this step. This part differs from the standard installation procedure, as the root password must be set outside of a chroot environment. Skipping this step will result on an impossibility to login.}}

Normally, for setting the password, one has to be able to run passwd. However that's not possible in this case since an x86 system can't run ARM binaries. Therefore, it is needed to modify the file that contains the passwords (/etc/shadow) to set a default root password.

===== Clearing the root password =====
This will allow to login with a blank password for the root user.
<console>
# ##i##nano -w /mnt/SD_root/etc/shadow
</console>

Modify the line beginning by "root" to match the following:
<pre>
root::10770:0:::::
</pre>

{{fancywarning|After initial login, remember to change the root password using the passwd command.}}

===== Choosing a root password (alternative) =====

First, generate a password. The output of this command will be used to modify the shadow file.
<console>
# ##i##openssl passwd -1
or
# ##i##python -c "import crypt, getpass, pwd; print crypt.crypt('password', '\$6\$SALTsalt\$')"
</console>

Then, edit the shadow file and use the output of the last command to replace "YOUR_PASSWORD_MD5".

<console>
# ##i##nano -w /mnt/SD_root/etc/shadow
</console>

<pre>
root:YOUR_PASSWORD_MD5:14698:0:::::
</pre>

==== Setup hostname and networking ====

Please read the [[Funtoo Linux Networking]] to configure your network.

==== Using swclock ====
One of the problems some of the devices have, is that they don't have a battery to save the clock time. To mitigate this, on Funtoo we have an option in our init system called swclock which sets the date of the system upon boot from a last modified date of a file.

First, add swclock to the boot runlevel.
<console>
# ##i##ln -sf /etc/init.d/swclock /mnt/SD_root/etc/runlevels/boot
</console>

Then, remove hwclock from the startup because it sets the date from the RTC, which is 2000-01-01 upon startup and overrides swclock's date.
<console>
# ##i##rm /mnt/SD_root/etc/runlevels/boot/hwclock
</console>

swclock uses the /lib/rc/cache/shutdowntime's modification time to set the date, therefore we update it to have the current date and time.
<console>
# ##i##touch /mnt/SD_root/lib/rc/cache/shutdowntime
</console>

Although this doesn't fix the issue, at least helps to set a sane date and time.
Note: Consider using NTP, documented on the next chapter

==== Enabling SSH access (optional) ====
Adding sshd to the default runlevel will enable access to the device using ssh.

<console>
# ##i##ln -sf /etc/init.d/sshd /mnt/SD_root/etc/runlevels/default
</console>

==== Enabling serial console access (optional) ====
By default the ttyS0 port is configured at 9600 bps. However, almost all of the ARM devices run the serial port at 115200 bps. Also, the port device names differ (ttyO2 for Pandaboard, ttySAC1 for Odroid-X ...). So edit your /etc/inittab file:

<console>
# ##i##nano -w /mnt/SD_root/etc/inittab
</console>

(For example for Pandaboard: )
<pre>
s0:12345:respawn:/sbin/agetty 115200 ttyO2 vt100
</pre>

=== Finishing the installation and booting up the new system ===
Let's unmount the SD card.
<console>
# ##i##umount /mnt/SD_root
</console>

Once you have the card ready, put it into your device, and you should be able to boot it. If you have a debug port you will be able to see the boot process using minicom or similar program on another PC connected with the debug cable.

[[Category:HOWTO]]
[[Category:ARM]]

Developer Guide

2012-12-27T08:37:20Z

Palica:

This page is intended to be a developer guide for Funtoo Linux.

Learning how to help squash out bugs can be a difficult thing to do, especially since sometimes JIRA looks a little overwhelming and confusing. A thank you to Daniel for making some videos (see below) on explaining this better, but there were a couple things left out. So I will take you through that. (With picture reference).

The first thing you're going to want to do is make an account, which is simple as clicking on the 'Log in' button on the top right, then clicking 'Sign up'.
[[File:Signupjira.png|720px|center]]

After you've made your account, the best way to watch bugs is to click on the 'Agile' drop-down menu, and choose 'Classic'.
[[File:Agileclassic.png|720px|center]]

Now, we're going to want to change a couple things even with this. By default, the 'Classic' mode takes you to 'Classic Planning Board', you want to change this to 'Classic Task Board'. This makes things much easier to read.
I also recommend going to the '''Views''' eyeball icon to the right and selecting the '''List''' issue view, and the '''Compact (Kanban)''' task board mode. This will give you a top-level overview of all our bugs and their statuses, and JIRA will remember your view preferences the next time you log in.

[[File:Classicview.png|720px|center]]

After that, we're almost ready to rock and roll. We need to also make sure that you're not set to any version or we'll only see a few bugs. So in case it says '1.1' or '1.0' change it to 'Unscheduled'.
[[File:Jiraversion.png|720px|center]]

And after all that, you can view and look at bugs that are in queue, To-do, or testing, which Daniel's videos are very great at explaining. Thanks for helping Funtoo Linux better and better.

<center>{{#widget:YouTube|id=JCg5DWjy6Ro|width=720}}

{{#widget:YouTube|id=tuFE9ZgVOpY|width=720}}

[[Category:Development]]

Linux Fundamentals, Part 1

2012-12-26T00:19:40Z

Palica: Undo revision 8334 by 88.7.197.57 (talk)

Funtoo Linux History

2012-11-18T20:42:29Z

Palica: /* Citations */

Funtoo arises from [[User:Drobbins|Daniel Robbins]]'s experience with [http://www.gentoo.org/ Gentoo] (and prior to that Stampede).

= Funtoo Linux History =

;'''Aug 25, 2010''': Perl 5.12 stabilized in Funtoo.
;'''Feb 1, 2010''': Sunrise removed from Funtoo.
;'''Jan 30, 2009''': Perl 5.10 integrated into Funtoo.
;'''Jan 8, 2009''': Git support integrated into Portage.
;'''Jan 6, 2009''': [http://www.gentoo.org/proj/en/sunrise/ Sunrise overlay] merged into Funtoo.
;'''Dec 15, 2008''': Metro 1.2 released.
;'''Nov 4, 2008''': Metro 1.1 released.
;'''Oct 18, 2008''': First version of [[Metro]], Linux automated build engine, released.
;'''Aug, 2008''': Daniel builds first unstable Gentoo stages -- requires modifications to upstream Gentoo tree.
;'''Jul 2008''': Daniel moves stages to 2008.0 profile.
;'''Dec 2007''': Daniel starts building Gentoo OpenVZ templates.
;'''Dec 2007''': Daniel starts building stable Gentoo stages.

= From Inception to Gentoo 1.0+ =

;'''Jun 10, 2002''': Gentoo Linux 1.2 released. :) <ref>http://www.linuxtoday.com/news_story.php3?ltsn=2002-06-12-016-26-NW-SW</ref>
;'''Apr 8, 2002''': Gentoo Linux 1.1a released. :)
;'''May 10, 2002''': Gentoo listed as one of the top 10 Linux distributions on [http://distrowatch.com/ DistroWatch].
;'''Mar 31, 2002''': Gentoo Linux 1.0 released!!! <ref>http://www.linuxtoday.com/news_story.php3?ltsn=2002-04-01-011-26-PR-CY-DV</ref>
;'''Feb 16-17, 2002''': Was in Brussels, Belgium to attend FOSDEM.
;'''Aug 14, 2001''': New Gentoo logo/web site debut -- designed by me! Still in use today! :)
;'''Dec 11, 2000''': Gentoo 1.0 Release Candidate 3 released.
;'''Nov 3, 2000''': Gentoo 1.0 Release Candidate 2 released.
;'''July 26, 2000''': Gentoo 1.0 release "imminent", CVS online, and rsync "coming soon".
;'''Late 1999''': Must have came back to Enoch and done the Gentoo name change right about now (the "Gentoo" name was Bob Mutch's idea). Started incorporating some FreeBSD ideas into Enoch... Portage (as we know it today) was born.
;'''Aug 1999''': My new dual Celeron mobo would not run Linux; went to FreeBSD, Achim Gottinger kept Enoch going.
;'''May 18-27, 1999''': First version of Enoch released, according to LWN.net. My blurb for Enoch: "Enoch is an advanced GNU/Linux distribution for the x86 PC Architecture, designed to bring your Linux experience into a new dimension. Or something like that." <ref>http://lwn.net/1999/0527/dists.php3</ref>
;'''Apr 1999''': Was working on Enoch. Wrote xpak .tbz2 code that is still in Portage.
;'''Nov 1998''': Was using/developing for Stampede Linux at home, but had not (yet) started Enoch?
;'''July 1997''': Started a new position at University of New Mexico, was using Debian 1.3.

= Citations =
<references/>

__NOTITLE__

[[Category:Funtoo]]

Funtoo Linux

2012-11-18T20:41:24Z

Palica: /* Funtoo Filesystem Hierarchy */

= Getting Started =
Start by [[Funtoo Linux Installation|installing Funtoo]]. If you have questions, someone has probably asked them already in our [[Funtoo Linux FAQ]]. Otherwise, there are other [[Funtoo Wiki:Community portal|community resources]] available. For more information on the vision of Funtoo, see: [[vision]]

= Differences between Funtoo Linux and Gentoo Linux =

From an installation perspective, the main difference between Funtoo Linux and Gentoo Linux is that Funtoo Linux has a different Portage tree. We store our Portage tree in a git repository. Our Portage tree does track the Gentoo repository (we import Gentoo changes almost every day,) but our tree does contain some significant changes from Gentoo's tree.

Here is a basic overview of how Funtoo Linux differ from Gentoo Linux:

{| {{Table}}
!||colspan="4" align="center" style="background-color: #ddf;"|stable||colspan="4" align="center" style="background-color: #f78888;"|current||colspan="4" align="center" style="background-color: #f70088;"|experimental
|-
!Category
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |Gentoo Linux
|style="background-color:#A0E75A;" |Funtoo Linux
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |Gentoo Linux
|style="background-color:#A0E75A;" |Funtoo Linux
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |Gentoo Linux
|style="background-color:#A0E75A;" |Funtoo Linux
|style="background-color: #f70088;"|
|-
!portage
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |2.1.10.49
|style="background-color:#A0E75A;" |2.3.3-r3 (funtoo)
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |~2.2.0_alpha100
|style="background-color:#A0E75A;" |2.3.3-r3 (funtoo)
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |2.3.3-r3 (funtoo)
|style="background-color: #f70088;"|
|-
!portage tree
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |rsync-based
|style="background-color:#A0E75A;" |git-based
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |rsync-based
|style="background-color:#A0E75A;" |git-based
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |git-based
|style="background-color: #f70088;"|
|-
!glibc
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |2.13-r4
|style="background-color:#A0E75A;" |2.11.3
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |2.14.1-r3
|style="background-color:#A0E75A;" |2.13-r4
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |2.13-r4
|style="background-color: #f70088;"|
|-
!gcc
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |4.5.3-r1
|style="background-color:#A0E75A;" |4.4.5
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |4.5.3-r2
|style="background-color:#A0E75A;" |4.6.2-r1
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |4.6.2-r1
|style="background-color: #f70088;"|
|-
!udev
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |171-r5
|style="background-color:#A0E75A;" |160-r3
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |182-r2/3
|style="background-color:#A0E75A;" |171-r3
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |171-r3
|style="background-color: #f70088;"|
|-
!init scripts
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |openrc
|style="background-color:#A0E75A;" |openrc
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |openrc
|style="background-color:#A0E75A;" |openrc
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |openrc
|style="background-color: #f70088;"|
|-
!perl
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |5.12.4-r1
|style="background-color:#A0E75A;" |5.12.4-r1
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |5.12.4-r2
|style="background-color:#A0E75A;" |5.14.2
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |gentoo unstable
|style="background-color: #f70088;"|
|-
!ruby
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |1.8.7_p357
|style="background-color:#A0E75A;" |1.8.7_p357
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |1.8.7_p357
|style="background-color:#A0E75A;" |1.8.7_p357
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |1.8.7_p357
|style="background-color: #f70088;"|
|-
!core openresolv
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |no
|style="background-color:#A0E75A;" |yes
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |no
|style="background-color:#A0E75A;" |yes
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |yes
|style="background-color: #f70088;"|
|-
!custom pkgs
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |[[Portage (Funtoo)|portage]], udev, grub, coreboot, openrc, and [http://github.com/funtoo/funtoo-overlay more]
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |[[Portage (Funtoo)|portage]], udev, grub, coreboot, openrc, and [http://github.com/funtoo/funtoo-overlay more]
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |[[Portage (Funtoo)|portage]], udev, grub, coreboot, openrc, and [http://github.com/funtoo/funtoo-overlay more]
|style="background-color: #f70088;"|
|-
!merged overlays
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |None
|style="background-color:#A0E75A;" |[https://github.com/slashbeast/foo-overlay slashbeast], [https://github.com/adessemond/bar-overlay A. Dessemond], [https://github.com/funtoo/flora flora]
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |None
|style="background-color:#A0E75A;" |[https://github.com/slashbeast/foo-overlay slashbeast], [https://github.com/adessemond/bar-overlay A. Dessemond], [https://github.com/funtoo/flora flora]
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |[https://github.com/slashbeast/foo-overlay slashbeast], [https://github.com/adessemond/bar-overlay A. Dessemond], [https://github.com/funtoo/flora flora]
|style="background-color: #f70088;"|
|-
!upstream tree
|colspan="1" style="background-color: #ddf;"|
|style="background-color:#87CEEB;" |None
|style="background-color:#A0E75A;" |gentoo stable
|style="background-color: #ddf;"|
|style="background-color: #f78888;"|
|style="background-color:#87CEEB;" |None
|style="background-color:#A0E75A;" |gentoo unstable
|style="background-color: #f78888;"|
|style="background-color: #f70088;"|
|style="background-color:#87CEEB;" |N/A
|style="background-color:#A0E75A;" |gentoo unstable
|style="background-color: #f70088;"|
|-
!||colspan="4" align="center" style="background-color: #ddf;"|stable||colspan="4" align="center" style="background-color: #f78888;"|current||colspan="4" align="center" style="background-color: #f70088;"|experimental
|}

= What are the differences between 'stable', 'current' and 'experimental' ? =

Funtoo Linux follows a continuous development cycle. This means that new packages are continuously added to the [[Portage Tree]] and others are periodically improved with patches and bug fixes.

When a package is considered to be stable, it is tagged as such, and means that you are very unlikely to have trouble with it during installation and in daily usage. All other packages are typically tagged as 'current' meaning they have undergone less widespread testing and you are more likely to experience issues with the software itself, or a package build failure. However, in day-to-day experience:

* Funtoo 'experimental' is the the development tree for CoreTeam members, it generally is the Funtoo 'current' tree to which tools are added that are right now at a testing, if one of these testing circles is done and finished the 'experimental' tree is merged into the 'current' tree and will so long not difer from it, until new packages with heavy impact are there for being tested. This tree is just designed for CoreTeam members as troubles might be more common here than in 'current'.

* '''Funtoo 'current' is almost as stable as Funtoo 'stable'''', although some troubles may appear from time to time. Some distributions name their 'current' branch 'unstable' but we do not because it implies that "unstable == unusable" (Funtoo current '''IS''' usable for a daily usage in production environments, depending on your requirements).

* Funtoo 'stable' can, per definition, lag '''a long ways behind''' 'current'. This branch is recommended for setting up servers which have standard and very well supported hardware for a long time. If you have a desktop machine which requires the most recent drivers / kernel available using 'stable' may not be a solution for you. Efforts are also made to ensure compatibility with stable Red Hat Enterprise Linux 5 kernels for use in environments where stability is of the utmost importance.

= What's Been Done So Far =

My technical goals for Funtoo Linux are to focus on improving the core Gentoo system, ie. what you'd find inside a stage3. I also have been working to improve general Gentoo technologies, such as migrating Portage to git, and ensuring that Funtoo is easily buildable in an automated way, by creating Metro. These changes are intended to empower me to improve Funtoo more easily, and are shared with you so that you can benefit from them as well.

These improvements are detailed below:

== Git-based Portage Tree ==

One of the first things I did was migrate Gentoo's development Portage tree from cvs to git, and migrate Gentoo's user Portage tree from rsync to git. This was done to help me work more effectively, since git is simply a much more powerful and efficient tool than cvs.

Zack Medico, Portage/emerge maintainer, has enhanced the 2.2 version of Portage so that it is compatible with git. This allows ''users'' to pull a Portage tree from a git repository. This can often be more efficient than rsync, although the git repository does take up more space on disk. But I did not switch away from rsync because it wasn't fast enough.

More important for me is the fact that users can pull from the same repositories that I use for Funtoo development. This simplifies Funtoo infrastructure considerably, keeping things more fun for me :)

Git also provides integrity-checking functionality that is superior to that which currently exists in Portage, which will allow improved data integrity checks in future versions of Portage. This work is not yet finished, or even really started, but by using git we are starting to move in this direction. This work will continue as I have time.

== Forked Tree ==

Funtoo has its own Portage tree that is 99% identical to Gentoo's Portage tree. I merge changes from Gentoo into our tree every 12 hours, using an automated process. Our tree has a few significant differences from the Gentoo Portage tree, which are covered in more detail in our [http://www.funtoo.org/en/articles/funtoo/quick-install-howto/ Quick Install Guide]

I created my own Portage tree for a multitude of reasons. The main reason for creating the tree was so I could get improvements into my Portage tree immediately, changes which Gentoo developers may or may not be interested in adding to the official Gentoo tree. I don't want to wait around or try to convince someone to add a fix I need.

== Metro and Daily Builds ==

[[Metro]] is a tool I created to build Gentoo and Funtoo releases in an automated way. For around a year, I have been using Gentoo's catalyst, and now [[Metro]] to build daily releases of Gentoo and Funtoo. These stages are available on the [[Download|Download page]].

Metro is a big improvement over Gentoo's automated build tool, catalyst, which I originally wrote but has not aged well over the years. Metro is still missing some functionality that exists in catalyst, most notably LiveCD support (I haven't created a Funtoo LiveCD yet, which is why :) but in nearly all other respects is much more capable than catalyst. I will continue to maintain and improve Metro as I have time. The daily builds serve as a good ongoing test for Metro as well as the integrity of the Funtoo Portage tree.

== Forkable - Empowering Developers ==

Combine the transition to git with Metro, and Funtoo is now actually quite easy to fork, unlike Gentoo. If you wanted to create your own derivative of Funtoo or Gentoo, you could simply clone my git repository and then set up Metro to build releases of this variant. With some basic familiarity with git, this can all be accomplished by an single individual in a single day.

Why is this important? If you love Gentoo like I do, but want to work on Gentoo independently, so that you have your own personal "fun, too" project where ''you'' are Chief Architect, you have all the tools you need to make this happen. There is no longer a need to become an official Gentoo developer in order to grow in your Gentoo knowledge.

== Core System Changes ==
Funtoo has several core system changes, and I plan to continue to focus on improving the core system quite a bit. Funtoo has its own <tt>sys-fs/udev</tt> package, its own <tt>sys-apps/baselayout</tt>, its own <tt>sys-apps/openrc</tt> (which is used by default), along with various other packages and improvements. Work is currently under way on a [[Unified Configuration]] structure as well as new, improved profile method which allows specifying multiple profiles (See [[Multiple Profiles]]).

== Articles ==
On the [[:Category:Articles|Articles]] page, you'll notice a number of technical articles and HOWTOs. My original IBM developerWorks Linux articles are gradually being added to the site and updated as time permits.

Every now and then, I will be adding interesting new content, such as the intriguing [http://www.funtoo.org/en/security/slowloris/ Slowloris DOS Mitigation Guide], which details various mitigations for the Slowloris DOS that affects the Apache Web server. This article was co-authored with Ryan Vick, a security researcher who is a friend of mine.

= What's in the Works =
In addition to various ongoing [[:Category:Projects|Funtoo Linux Projects]], there are other efforts.

== Funtoo Filesystem Hierarchy ==

The [[Funtoo Filesystem Hierarchy]] seeks to document the specific nuances of the Funtoo fileystem hierarchy beyond what is in the [http://pathname.com/fhs/ Filesystem Hierarchy Standard] already.

[[Category:Funtoo]]

Funtoo Basic concepts

2012-11-18T20:40:51Z

Palica:

The following article is about several concepts which are very important to clearly understand how Funtoo works.

= Funtoo branches =

= Keywording and USE flags =

== An analogy ==

This is most probably the '''most fundamental and central point''' to understand as it covers how the package management in Funtoo works "coast-to-coast". Basically this is extremely simple and pretty easy understand with a little analogy in your daily life: you are due to go the the grocery and several places around and to not forget what you have to do, you put on the list several items like:
* Grocery:
** Bread
** Eggs
** Butter
* Bank $40
* Photos

When you will follow your list, every item will trigger an action like making you go in a particular section in the grocery to put a bag of bread in your basket or going to the bank outlet to withdraw $40. Those list items are a bit like switches: if you write (define) the item you turn a switch on making you take the appropriate action, if you don't write an item on the list you leave the switch turned off and you won't do something special.

Items on the list are, by ''convention'', related to what they denote: the good sense makes you write "beer" to make you remember to buy some beer. Technically, you can achieve the exact same thing by writing "cookies" or "butter" (unless some very good reason like hiding some evil intentions to the eyes of your house overlord ;-)). If you give your list to someone else and because, by convention, itemns on your list denotes what they are related to

Portage will follow a similar behaviour, although more subtle: depending on the "grocery list items" you define at various places in the system you can govern how Portage acts (what features present on the system it is allowed to use, which are the packages it can consider or forget about, and so on. Those switches are split among several categories like:
* '''Features''' for those that control the features portage can use or can't use (like "you can use distcc if present" or "you can fetch the source code archive in the background" or "keep aside a binary archive of a package once compiled" or "Use ccache if present")
* '''USE flags''' for those that governs what features are activated in the different packages you install on a machine. USE flags are a bit more subtle in practise because they can also express extra action to take care of like "download and copy the package official documentation in /usr/share/doc" or "automatically add a symlink /usr/bin/blahblah which points to /usr/bin/mypackage". It is not easy to give a general case here due to the lack of a rigid rule telling what USE flag should do what (exact care given by portage varies from package to package depending on what orders are written in the ebuild file), those are only a '''convention'''.
* '''Keywords'''

= Portage and Portage tree =

= Profiles =

[[Category:Funtoo]]

Funtoo ARMv7

2012-11-18T20:37:07Z

Palica:

This is currently a scratch page for getting an ARMv7 build working for Funtoo:

<pre>
# echo 'sys-devel/crossdev **' >> /etc/portage/package.keywords
# emerge layman crossdev
# echo 'PORTDIR_OVERLAY=/usr/local/portage' >> /etc/make.conf
# install -d /usr/local/portage
# layman -a gentoo-arm
# crossdev -t armv7-none-linux-gnueabi
</pre>

[[Category:ARM]]

Fonts

2012-11-18T20:36:54Z

Palica: /* LibXft */

== LCD-Filtering overlay ==
Funtoo Linux planning to integrate LCD-filtering overlay into main tree in order to have very good font experience. Before that the overlay available via layman and manual steps required as described below. Overlay consist of patched versions of <tt>cairo</tt>, <tt>libXft</tt>, <tt>fontconfig</tt>, <tt>freetype</tt> with the aim of getting nice hinting and rendering, emulate the Ubuntu/MS Windows/Mac OS X fonts appearance.
== Install the packages ==
<console> # emerge -uN fontconfig freetype cairo libXft</console>
== Advanced configuration ==
=== Fontconfig ===

=== Default configuration ===

<console>eselect fontconfig enable 10-antialias.conf
eselect fontconfig enable 10-autohint.conf
eselect fontconfig enable 10-hinting.conf
eselect fontconfig enable 10-hinting-slight.conf
eselect fontconfig enable 10-sub-pixel-rgb.conf
eselect fontconfig enable 11-lcdfilter-default.conf
eselect fontconfig enable 70-no-bitmaps.conf
eselect fontconfig disable 10-hinting-full.conf
eselect fontconfig disable 10-hinting-medium.conf
eselect fontconfig disable 10-no-sub-pixel.conf
eselect fontconfig disable 10-sub-pixel-bgr.conf
eselect fontconfig disable 10-sub-pixel-vbgr.conf
eselect fontconfig disable 10-sub-pixel-vrgb.conf
eselect fontconfig disable 10-unhinted.conf</console>
===Linux configuration ===

Same as default configuration except:
<console>eselect fontconfig enable 21-hinting-small-aquabase-slight.conf
eselect fontconfig enable 21-hinting-small-browallia-slight.conf
eselect fontconfig enable 22-hinting-courier-italic-slight.conf</console>
=== Infinality’s configuration ===

Same as default configuration except:
<console>eselect fontconfig enable 15-hinting-tt-instructed-full.conf
eselect fontconfig enable 20-hinting-small-fonts-slight.conf
eselect fontconfig enable 21-hinting-small-aquabase-slight.conf
eselect fontconfig enable 21-hinting-small-browallia-slight.conf
eselect fontconfig enable 22-hinting-courier-italic-slight.conf
eselect fontconfig enable 25-hinting-small-arial-black-slight.conf</console>
=== Windows configuration ===

Same as default except:
<console>eselect fontconfig disable 10-autohint.conf
eselect fontconfig disable 10-hinting-slight.conf
eselect fontconfig enable 10-hinting-full.conf
eselect fontconfig enable 15-hinting-non-tt-instructed-slight.conf
eselect fontconfig enable 20-hinting-small-fonts-slight.conf
eselect fontconfig enable 21-hinting-small-aquabase-slight.conf
eselect fontconfig enable 21-hinting-small-browallia-slight.conf
eselect fontconfig enable 22-hinting-courier-italic-slight.conf
eselect fontconfig enable 25-hinting-small-arial-black-slight.conf</console>
=== OSX ===

Same as default configuration except:
<console>eselect fontconfig disable 10-autohint.conf
eselect fontconfig disable 10-hinting.conf
eselect fontconfig disable 10-hinting-slight.conf
eselect fontconfig enable 10-unhinted.conf
eselect fontconfig enable 15-hinting-tt-instructed-none.conf</console>
== Freetype ==
Freetype can be configured through environment variables (see <tt>/etc/env.d/99lcdfilter</tt> for a list of the variables and their description). Those variables can be overridden on a per-user basis by either redefining them in a startup file (such as <tt>~/.bash_profile</tt>) or by sourcing the <tt>/usr/lib/ft-settings.sh</tt> script with the desired style in parameter (you can, of course, source the script from a startup file).

usage: source ft-settings.sh <style>

<console>Possible styles:
default - Use default settings. A compromise that should please most people
osx - Simulate OSX rendering
ubuntu - Simulate UBUNTU rendering
linux - Generic Linux style - no snapping or certain other tweaks
windows - Simulate Windows rendering
vanilla - Just subpixel hinting

Infinality styles:
classic - Infinality rendering circa 2010. No snapping
nudge - CLASSIC with lightly stem snapping and tweaks
push - CLASSIC with medium stem snapping and tweaks
shove - Full stem snapping and tweaks without sharpening
sharpened - Full stem snapping, tweaks, and Windows-style sharpening
infinality - Settings used by Infinality</console>
== LibXft ==
Only legacy programs still use libXft. The default configuration is defined in <tt>/usr/share/X11/app-defaults/Xft</tt>. It can be overriden on a per-user basis in the <tt>~/.Xresources</tt> or <tt>~/.Xdefaults</tt> files :

<console>Xft.antialias: 1
Xft.autohint: 0
Xft.dpi: 96
Xft.hinting: 1
Xft.hintstyle: hintfull
Xft.lcdfilter: lcddefault
Xft.rgba: rgb</console>

[[Category:HOWTO]]

Extlinux

2012-11-18T20:36:37Z

Palica: /* manual extlinux.conf */

= What is ExtLinux? =

ExtLinux is a pretty simple and modern systemloader, bundled with the syslinux tools, installation is really simple for it and fast, and thanks to our CoreTeam member Slashbeast the configuration runs automated in an awesome way.

= Installing ExtLinux for funtoo =

Installing ExtLinux for funtoo is known to work and supported too. If you like to try it just emerge syslinux

<pre>
# emerge syslinux
</pre>

with that you have the complete syslinux tools installed. Another helpful tool you should merge with syslinux is slashbeast's lazykernel tool, so let us merge it too:

<pre>
# emerge lazykernel
</pre>

== Installing extlinux ==

to install extlinux just follow these steps:

<pre>
# install -d /boot/extlinux
# extlinux --install /boot/extlinux
# cd /boot
# ln -s . boot
</pre>

the next steps are different depending if you use an MBR or GPT setup and the HDD you installed on and want to boot from. Let us now for general take /dev/sda as your boot device.

=== MBR ===

If you set up your disk with MBR partition scheme just do the next steps:

<pre>
# dd bs=440 conv=notrunc count=1 if=/usr/share/syslinux/mbr.bin of=/dev/sda
# cp /usr/share/syslinux/menu.c32 /boot/extlinux/
# touch /boot/extlinux/extlinux.conf
</pre>

=== GPT ===

<pre>
# sgdisk /dev/sda --attributes=1:set:2
# sgdisk /dev/sda --attributes=1:show
1:2:1 (legacy BIOS bootable)
# dd bs=440 conv=notrunc count=1 if=/usr/share/syslinux/gptmbr.bin of=/dev/sda
# cp /usr/share/syslinux/menu.c32 /boot/extlinux/
# touch /boot/extlinux/extlinux.conf
</pre>

== Setting up the Kernel ==

Now if you followed our advice to install lazykernel we have a pretty nice way to solve all the setup with a bit of prework and finish it then. If not you should go to the manual part. :)

=== lazykernel way ===

As you setup lazykernel, we now need to edit /etc/lazykernel.conf

make it to look like somethink like that:

<pre>
# After configuring, hash or remove line below.
#CONFIGUREFIRST

# Number of the kernels to keep so `lazykernel clean` will not propose to remove them. Default: 3
keep_kernels=5

# Sort kernels by 'version' (biggest version first) or by 'mtime' (latest images first). Default: mtime
# Sorting by version may fail and 3.3.0-rc2 will be marked as newer than 3.3.0.
#sort_by='version'
sort_by=mtime

# The name for menu entry.
menu_entry_name="Funtoo Linux"

# Specify what initramfs image to use, if any. (Optional)
initramfs='initramfs.cpio.gz'

# Append kernel params, usualy you use it to specify rootfs device, but you can use it to pass switches to initramfs as well. (Optional)
#kernel_params='root=/dev/sda2'
#kernel_params="rootfstype=ext4 luks enc_root=/dev/sda2 lvm root=/dev/mapper/vg-rootfs uswsusp resume=/dev/mapper/vg-swap"
kernel_params="rootfstype=ext4 luks enc_root=/dev/sdb3 lvm root=/dev/mapper/vg-root uswsusp resume=/dev/mapper/vg-swap"
</pre>

please make sure to comment out or delete the second line of the config file, else it will spit out an error for you... :)

Now let us setup our kernel with lazykernel if you have a manual kernel just run:

<pre>
# cd <kernel build dir>
# lazykernel auto
</pre>

that will generate the modules for you, copy your kernel form /usr/src/linux over to /boot and generate the /boot/extlinux/extlinux.conf for you. The manual kernel will be the only supported one by lazykernel.

That's all you are ready to boot. :)

=== manual extlinux.conf ===

For other kernels, like those created by genkernel or by the binary USE-flag you need to edit your config by yourself. Just open /etc/extlinux/extlinux.conf in your favorite editor and setup something like the following:

<pre>
TIMEOUT 30
UI menu.c32

MENU TITLE Boot Menu
MENU COLOR title 1;37;40
MENU COLOR border 30;40
MENU COLOR unsel 37;40

LABEL funtoo1
MENU LABEL Funtoo Linux KERNEL-VERSION
LINUX /<kernel>
INITRD /<initramfs>
APPEND rootfstype=ext4 luks enc_root=/dev/sdb3 lvm root=/dev/mapper/vg-root uswsusp resume=/dev/mapper/vg-swap
</pre>

That's all again you are ready for boot. You can also define several LABELs in that list to have multiple kernels been booted... :)

[[Category:HOWTO]]

Ebuild Maintainer list

2012-11-18T20:31:57Z

Palica:

As we would like to keep track of who is responsible and how we could contact him it would be nice to have you subscribed in the following list with the ebuild and your data to contact you.

{| border="2" cellpadding="4" cellspacing="0" style="width:75%; margin:1em 1em 1em 0; background:#fafafa; border:1px #aaa solid; border-collapse:collapse; font-size:95%; caption-side:bottom;"
|-
! !! ebuild !! Name !! IRC Contact !! Wiki User !! Other Contact
|-
! A
|-
|
|-
! B
|-
| || x11-misc/bumblebee || Michael Ketslah || ZogG || [[User:ZogG|ZogG]] || see user page
|-
! C
|-
|
|-
! D
|-
|
|-
! E
|-
| || eclipse-sdk || Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
| || eclipse-sdk-bin || Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
! F
|-
| || media-video/freeseer || Patrick McMunn || PaddyMac || [[User:PaddyMac|PaddyMac]] || see user page
|-
| || fribid || Edward Tjörnhammar || edwtjo || [[User:Edwtjo|Edwtjo]] || see user page
|-
! G
|-
|
|-
! H
|-
|
|-
! I
|-
|
|-
! J
|-
| || jsl || Jean-Francis Roy (ebuild from felicitus overlay) || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
! K
|-
|
|-
! L
|-
| || lucene-analyzers || Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
! M
|-
| || minetest || Edward Tjörnhammar || edwtjo || [[User:Edwtjo|Edwtjo]] || see user page
|-
| || safecopy || Markus Maiwald || mmatk || [[User:Mmatk|Mmatk]] || see user page
|-
| || media-gfx/makehuman || Sandy-Marko Knauer || knasan || [[User:Knasan|Knasan]] || see user page
|-
! N
|-
|
|-
! O
|-
| || oblogout || Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
| || oxygen-fonts || Rafael Fernández López || ereslibre || [[User:Ereslibre|Ereslibre]] || see user page
|-
! P
|-
| || palm-novacom || Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
| || pyroom || Martin Scholz || golodhrim || [[User:Golodhrim|Golodhrim]] || see Bio
|-
! Q
|-
! R
|-
! S
|-
| || splash-themes-funtoo || ryo || ryo || [[User:ryo|Ryo]] || see user page
|-
| || shogun || Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
| || media-libs/silly || Patrick McMunn || PaddyMac || [[User:PaddyMac|PaddyMac]] || see user page
|-
| || spotify || Rafael Fernández López || ereslibre || [[User:Ereslibre|Ereslibre]] || see user page
|-
| || sublime-text || Rafael Fernández López || ereslibre || [[User:Ereslibre|Ereslibre]] || see user page
|-
| || svmlight || Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
! T
|-
| || theano|| Jean-Francis Roy || jeanfrancis || [[User:Jeanfrancis|JeanFrancis]] || see user page
|-
| || thinkfan || Rafael Fernández López || ereslibre || [[User:Ereslibre|Ereslibre]] || see user page
|-
| || traGtor || Kai Korla || balticer || [[User:balticer|balticer]] || see user page
|-
! U
|-
! V
|-
! W
|-
| || games-fps/warsow || Ari Malinen || defer || [[User:defer|defer]] || see user page
|-
! X
|-
| || xfce-base/xfwm4 || Roman v. Gemmeren || strowi || [[User:strowi|strowi]] || see user page
|-
! Y
|-
! Z
|}

[[Category:Development]]

Lenovo Thinkpad T420

2012-11-18T20:27:56Z

Palica: Palica moved page Dossier: Lenovo Thinkpad T420 to Lenovo Thinkpad T420

== Introduction ==
Throughout, this article will assume the following:
* You have installed Gentoo or Funtoo in the past.
** If you haven't, this article will still serve you well, but please have either the official funtoo, or gentoo install guides open. We move through non-machine-specific bits with little elaboration.
* Have a T420 or similar machine.

Even if you do not have a T420, you may find this guide useful for:
* Nvidia Optimus Cards.
* Power management.
* General setup.

This installation assumes (For now) that the install is starting from an MS-Windows installation. If you are not on Windows, please add your favourite choice of steps, keep the emphasis on ease of understanding.

== Getting Started ==
You'll want to get yourself running off a LiveCD or LiveUSB to start. This guide will assume liveUSB, since some users find them more difficult to prepare, this is usually due to boot flag issues.
(Note: ''Live USB restore drives are nice to have in general! The author keeps one in his college binder.'')

==== Windows ====
We can use LiLi for this, it provides a nice, simple interface and is fairly reliable: [http://www.linuxliveusb.com/en/download LiLi Download]

=== SysrescueCD ===
Grab the version that Suites your needs here: [http://www.sysresccd.org/Download Sysrescue Download]
Next use LiLi (Or whatever you happen to be using) to flash the image or burn your CD. Reboot, change your boot device, and you'll find yourself at a grub menu.

Since the T series are all 64-bit laptops, make sure to boot the 64-bit kernel, as the default is 32-bit.

''But Why?: If we pick 32-bit, later on we won't be able to chroot into our Funtoo's 64-bit stage 3.''

You should see a fairly verbose boot as sysrescueCD scans for modules it requires and starts up. It is safe to simply accept prompt defaults here, unless they are errors.

When you are greeted by the interactive command prompt, enter 'wizard' as prompted, and accept the default entry in the dialogue. This will give us a functioning XFCE desktop environment.

== Partitioning ==
Partitioning is the only step of this install which provides real risk to data on other operating systems. Be extremely careful if there is something you do not wish to loose. These steps are not foolproof and may result in lost data.

Please be aware that MBR disks only support '''4''' primary partitions. You can solve this by creating an 'extended' partition and adding logical partitions to it. If you are feeling particularly brave try GPT on your disk.

So lets start:
First open up gparted. You should see it on the taskbar if you're using systemrescueCD. It will scan available drives and show you the partition table. Most users will likely find one of the following to their liking:

==== Pure Funtoo ====
You'll likely want:
<pre>
/boot :: EXT2 :: 100mb-500mb
''Note: We choose EXT2 because there is really no good use for a journalled boot partition, but feel free to use EXT4 instead!''
/ :: EXT4 :: 60gb (suggested floor value) - 500+
swap :: linux-swap :: Your RAM Value (Optional, allows for hibernation)
</pre>
You may wish for a separate /home, which is perfectly legitimate, or any number of other partitions.

==== Dual Boot with Windows ====
If dual booting with Windows, it is advisable to have Windows installed '''first''' since it will muck with the MBR and possibly want to create it's own boot partition.
You'll likely want:
<pre>
System Reserved :: NTFS :: Whatever windows chooses.
Windows :: NTFS :: >100gb (If you plan on doing any serious work on windows)
/boot :: EXT2 :: 100mb-500mb
Extended Partition -
/ :: EXT4 :: Whatever is left.
swap :: linux-swap:: Your RAM value. (Optional, allows for hibernation)
</pre>
You may also want a separate /home, etc. These will fit into your extended partition without contributing to MBR's 4 partition limit.

== Starting the (actual) Install ==
Up until now everything we've done has just been foreplay. Finally we can mount our partitions and get started on the installation!

==== Mounting ====
First, lets mount all of our partitions.
* Make a directory for root. Lets assume '''/mnt/funtoo'''
<pre>
mkdir /mnt/funtoo
</pre>
* Mount your '/' partition to /mnt/funtoo
<pre>
mount /dev/sd## /mnt/funtoo
</pre>
* Make a directory for your boot partition.
<pre>
mkdir /mnt/funtoo/boot
</pre>
* Mount your boot partition.
<pre>
mount /dev/sd## /mnt/funtoo/boot
</pre>
* Mount anything else you may have made and need. (Not swap)

==== Checking the Date ====
Although this may seem super un-important, if you want to avoid lots of spammy warning messages later, checking your date is beneficial.
<pre>
date
</pre>
If it needs to be set, you'll want something like:
<pre>
date 071620002011
#Fri Jul 16 20:00:00 UTC 2011
</pre>

==== Fetch a Stage 3 ====
Next we need to fetch a tarball containing a barebones stage. We will download the core-i7 architecture version, if you have a core i5 or i3, don't worry, it's all the same.
<pre>
cd /mnt/funtoo
wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/x86-64bit/corei7/stage3-current.tar.xz
</pre>

Next lets unpack with
<pre>
tar xJpf stage3-current.tar.xz
</pre>
''Seriously, don't forget the 'p' option.''

If you run 'ls' now, you should see the /mnt/funtoo is fully populated with folders such as lib, home, and proc.

==== Chroot'ing ====
Now we need to change the ''apparent root'' of our system to our fledgling Funtoo system.
<pre>
cd /mnt/funtoo
mount --bind /proc ./proc
mount --bind /dev ./dev
cp /etc/resolv.conf ./etc
env -i HOME=/root TERM=$TERM chroot /mnt/funtoo /bin/bash --login
</pre>

==== Getting the Portage Tree ====
Funtoo (Unlike Gentoo) uses a git based portage tree, however if you're coming from Gentoo, you'll be glad to know we sync with the Gentoo tree once every 12 hours.
<pre>
emerge --sync
</pre>
''You can ignore most of the errors that might be spat out at this stage, however if they do not disappear on subsequent merges, talk to us in #funtoo.''
Your first sync will take significantly longer then subsequent syncs, as the whole tree must be synced.

==== A Configuration Celebration ====
Now that we have our portage tree cloned, we need to do some initial setup on some files before doing anything else with portage.

'''Fstab'''

<pre>
nano /etc/fstab
</pre>

You'll want something like this: (Replace the dev values with what you are using)
<pre>
# <fs> <mountpoint> <type> <opts> <dump/pass>

/dev/sda1 /boot ext2 noauto,noatime 1 2
/dev/sda3 none swap sw 0 0
/dev/sda4 / ext4 noatime 0 1
/dev/cdrom /mnt/cdrom auto noauto,ro 0 0
</pre>

'''Localtime'''

Lets remove the default localtime, and create a symbolic link to the proper time zone. (You probably will want something other then Vancouver)
<pre>
rm /etc/localtime
ln -s /usr/share/zoneinfo/America/Vancouver /etc/localtime
</pre>

''' Hostname '''
Set your host name:
<pre>
nano /etc/conf.d/hostname
</pre>

'''hwclock'''

If you're using a dual boot system, you'll want to change this. Otherwise it's entirely optional.
<pre>
nano /etc/conf.d/hwclock
</pre>

If you're on windows you'll want:
<pre>
clock="local"
</pre>

'''Make.conf'''
Important enough that it deserves it's own article. A template make.conf for the T420 will be forthcoming.

For now:
If you have an i5 or i3 you will want
<pre>
MAKEOPTS="-j3"
</pre>
If you have an i7 you'll probably want
<pre>
MAKEOPTS="-j5"
</pre>

''But I have Hyperthreading! Why only -j3?''
Hyperthreading and compiling don't play well together. You'll have the same (or better) performance with -j3 as -j5 with a dual core hyper threaded processor.

== Stop, Kernel time! ==
''For this guide we'll be using some pre-found config options that I will be adding later.''

* Networking:
** iwlwifi and auxilary
** Unknown intel ethernet adapter. Selected several.
* GPU
** Intel available default.
** nvidia will be dealt with later

Install:
* wpa_supplicant
* iwl6000-ucode
* wireless-tools

== Bootloader Setup ==
In funtoo the setup of grub is extremely simplified.
<pre>
emerge -vqat boot-update
</pre>
''Q: What are those options? A: We'll get to them later, lets get the system booted first, okay? ''
Boot-update is a tool that will allow for very simple configuration of grub similar to older versions (But nicer still).

You will now find a file:
<pre>
$ cat /etc/boot.conf
boot {
generate grub
default "Funtoo Linux genkernel"
timeout 3
}

"Funtoo Linux" {
kernel bzImage[-v]
# params += nomodeset
}

"Funtoo Linux genkernel" {
kernel kernel[-v]
initrd initramfs[-v]
params += real_root=auto
# params += nomodeset
}
This can be configured (We'll touch on this later. We need to make sure the kernel is booting and working before we start tweaking) with options for the kernel.

==== Dual-Booters Only ====
If you want to dual boot with windows you'll need to add an entry here:
<pre>
"Windows 7" {
type win7
params root=/dev/sda1
}
</pre>
==== Installing Grub onto the Drive(Everyone) ====
Next we can install grub onto the drive.
<pre>
grub-install --no-floppy /dev/sda
boot-update
</pre>
No errors means we should be good to go!

== Tidy up and go. ==
Just a few more things!

Lets set a root password.
<pre>
passwd
</pre>

It is advisable to exit the chroot and umount all the relevant install drives. Or at least just exit the chroot, but you can just simply reboot from here.
<pre>
exit
cd /
umount /mnt/funtoo/boot /mnt/funtoo/dev /mnt/funtoo/proc /mnt/funtoo
reboot
</pre>

== Configuring the New System ==
Welcome to funtoo! You should be greeted by a bunch of spammy text that scrolls by reasonably fast and then a couple penguins and openrc. Login to your root user and lets start playing.

A note, this part of the guide is meant to be much more of a dialogue between us.

==== Getting up the (wired) network ====
If you're gifted with a wired network connect, use it! The initial setup is much more convenient and quick.

Quickly set up the network with
<pre>
/etc/init.d/dhcpcd start
</pre>
Now check to see if our wired adapter is listed with ifconfig.
<pre>
ifconfig
# (or)
ping google.com
</pre>
If you see it listed with a description, we're good to go!

==== Making the make.conf ====
Before we start merging into our tree everything under the sun, lets do some system planning.

You can use this as a starting point:
<pre>
# These settings were set by the metro build script that automatically built this stage.
# Please consult /etc/make.conf.example for a more detailed example.

ACCEPT_KEYWORDS="~amd64"
CHOST="x86_64-pc-linux-gnu"
CFLAGS="-march=corei7 -O2 -pipe"
CXXFLAGS="-march=corei7 -O2 -pipe"
SYNC="git://github.com/funtoo/ports-2012.git"

# -j3 :: Have make use 3 threads by default.
MAKEOPTS="-j3"
# Setup emerge's default options:
# --ask :: Double check before merging.
# --verbose :: Show use flags etc.
# --quiet :: Don't show me make spam.
# --tree :: Use nice dependancy graphs.
EMERGE_DEFAULT_OPTS="--ask --verbose --quiet --tree"

# Portage Features
# TODO: Descriptions
FEATURES="mini-manifest parallel-fetch userfetch parallel-install sandbox fixpackages collision-protect"

# We might use binary packages later. Lets set that up just in case.
PORTAGE_BINHOST=/usr/portage/packages

# CCache
# This is not going to be done by default.
# Why? It's only wortwhile if you plan on compiling packages multiple
# times per version, which the average user will not.
#CCACHE_SIZE="5G"
#CCACHE_DIR="/var/cache/ccache"

# Licenses
# By default we're just going to accept everything.
ACCEPT_LICENSE="*"

# Device Specific Settings
# INPUT_DEVICES :: A list of input devices you'll be wanting. This is needed for xorg and not much else.
INPUT_DEVICES="evdev synaptics"
# VIDEO CARDS :: A list of video cards. Optimus users beware here.
VIDEO_CARDS="intel i915 i965 nvidia"

# Use flags.
# Application specific flags should be migrated to /etc/portage/package.use (which can be a folder with multiple files!)
# To look at the user flags for an application use "equery uses FOOPKG"
USE="
acpi alsa /
bash-completition /
curl /
dvdr /
ithreads /
ncurses networkmanager/
policykit /
ssl sse sse2 sse3 sse4 /
threads /
udev /
vim-syntax /
zsh-completion /
"
</pre>

==== Getting an Editor ====
Well, first things first lets get ourselves an editor. The author prefers vim, but you may like emacs or something else... Feel free to disregard this and explore! If you plan to have multiple users however, this will often be expected by experienced linux users.

<pre>
emerge vim
</pre>
Check that your USE flags look reasonable (see above) and feel free to do any fine tweaking in /etc/portage/package.use.
Consult your output after merge! You may want to follow some of it's advice.

You can find multiple good guides on google for vim configurations and setups.
Funtoo also provides a very nice base configuration in /etc/vim/vimrc.

==== Boot Parameters ====
The T420 has a number of boot parameters that can be set to conserve power. On a laptop these options are generally reasonable:
<pre>
$ cat /etc/boot.conf
boot {
generate grub
default "Funtoo Linux"
timeout 15
}

"Funtoo Linux" {
kernel bzImage[-v]
# Force PCIE Active State Power Management on.
params += pcie_aspm=force
# TODO (Range 1..15)
params += epb=7
# TODO
params += hpet=force
# i915 Enable rc6 sleep state (?)
params += i915.i915_enable_rc6=1
# TODO (Framebuffer?)
params += i915.i915_enable_fbc=1
# Downclock the lvds screen (60hz -> 50hz)
params += i915.lvds_downclock=1
# Quiet some of the excessively verbose kernel boot
params += quiet
}

"Windows 7" {
type win7
params root=/dev/sda1
}

#"Funtoo Linux genkernel" {
# kernel kernel[-v]
# initrd initramfs[-v]
# params += real_root=auto
#}
</pre>

When you're done, update grub with
<pre>
boot-update
</pre>

==== Power Saving Local Scripts ====
Next we're going to set up a script that runs at default runlevel for the machine. This will echo several options to various dev files. Most distros would do this via /etc/rc.local or something of the like.

With Funtoo (and Gentoo) this is accomplished via
<pre>
/etc/local.d
</pre>
Consult the README (in directory) for more information.

<pre>
$ cat /etc/local.d/power-saving.start
# /bin/bash
#
echo 1 > /sys/modules/snd_hda_intel/parameters/power_save
for i in /sys/bus/usb/devices/*/power/autosuspend; do
echo 1 > $i
done
for i in /sys/class/scsi_host/host*/link_power_management_policy; do
echo min_power > $i
done
</pre>
If you copy this wholesale remember to chmod -x the file!

==== rc.conf ====
rc.conf lets us change some options to do with open RC.

First, lets set rc_sys to it's default, this will suppress a warning message at boot.
<pre>
rc_sys=""
</pre>

Next, we can turn on rc_parallel to get a bit of speedup on boot.
<pre>
rc_parallel="YES"
</pre>
If you get errors or problems with services on boot, try turning this off.

== Making it Usable ==
Next we'll be setting up a normal user and installing the venerable Xorg.

==== Mouse in framebuffer ====
Right now we should be looking at a framebuffer'd console.
<pre>
/etc/init.d/gpm start
</pre>
gpm is a daemon that allows us to use our mouse (trackpad/trackpoint) on console. Give it a try! If you want to keep it on across boots, add it to your init.
<pre>
rc-update add gpm default
</pre>

==== Making a New User =====
Lets use superadduser to make the task ever so much easier (Though, it is already easy)
<pre>
emerge superadduser
superadduser
</pre>

Walk through the prompts and set up your user how you choose.

==== Sudo Make Me a Sandwich ====
Next lets merge in sudo, and set up our new user to be able to use sudo.
<pre>
emerge sudo
</pre>
Now edit the config with
<pre>
visudo
</pre>
You'll probably want to uncomment out one of the two options:
<pre>
## Uncomment to allow members of group wheel to execute any command
# %wheel ALL=(ALL) ALL

## Same thing without a password
# %wheel ALL=(ALL) NOPASSWD: ALL
</pre>

Now just add your user to the 'wheel' group.
<pre>
gpasswd -a foouser wheel
exit
</pre>
Now re-login as your user, and you should be good to go!

==== Tmux ====
Before we emerge xorg, lets get tmux working so we can easily scroll through output and look at USE flags etc.
<pre>
emerge tmux
</pre>
The default config will suffice for now. You may find it beneficial to learn to use tmux ''properly'' sometime, but for now we'll hold hands.

<pre>
tmux
</pre>
Now we can scroll through output with CTRL+B [ and the up and down arrows.

== Xorg ==
Xorg is a large topic in and on itself. We'll focus on getting a working xorg and a simple window manager.

<pre>
# (in tmux)
sudo emerge xorg-server
</pre>
Once again use CTRL+B [ to start scrolling (escape to exit) and look through your use flags, adding anything you might want.

== A note on Gnome ==
Want to get rid of that awful lock screen on wake from suspend?
<pre>gsettings set org.gnome.desktop.lockdown disable-lock-screen 'true'</pre>

[[Category:HOWTO]]
[[Category:HWLaptop]]

Lenovo Thinkpad T420

2012-11-18T20:27:33Z

Palica:

Desktop-install

2012-11-18T20:26:04Z

Palica:

{{delete}}

Nothing to See here! What you are looking for is the [[Funtoo_Linux_Installation]] or, for the brave adventurer, [[Installation_(Tutorial)]]

Core Team

2012-11-18T20:25:23Z

Palica:

== Your Staff ==

Funtoo Linux Core Team members are Funtoo Linux developers who are actively contributing to technical aspects of Funtoo Linux, and are available for resolving bugs and other QA issues. Please see [[Core Team Responsibilities]] for general policies, [[Funtoo Linux Vision]] for an understanding of strategic direction, and [[TODO]] for immediate things that need to get done.

=== Project Leadership ===

;Benevolent Dictator for Life: [[User:Drobbins|Daniel Robbins]] is the Chief Architect of Funtoo Linux, and so-called "Benevolent Dictator for Life."
;Core Team Lead: [[User:Oleg|Oleg Vinichenko]] - ''angry_vincent'' is the senior member of the Funtoo Linux development team.

=== Staff ===

Funtoo Linux staff includes our Core Team of developers and participates in the continued operation and improvement of Funtoo Linux:
{{#ask: [[Category:People]] [[Role type::Staff]]
| ? Full name
| ? Nick
| ? Role desc
| ? Start date
| format=template
| template=TeamList
| link=none
}}

=== Staff and Contributor Map ===

{{#compound_query:[[Category:People]] [[Role type::Staff]];?Geoloc;icon=Purplemarker.png
|[[Category:People]][[Role type::Contributor]];?Geoloc;icon=Orangemarker.png
|format=googlemap|height=500}}

=== Where to Find Us ===

The Funtoo team can often be found in the [ircs://irc.freenode.net:7000/funtoo|funtoo channel on Freenode]. The team also monitors the [http://forums.funtoo.org/ Funtoo Forum] and [https://groups.google.com/group/funtoo-dev/ mailing list].

=== Contributors ===

Contributors are active Funtoo Linux developers who have made significant contributions to Funtoo Linux, as well as former Core Team members who are currently inactive. Some contributors have overlays that are automatically incorporated into the Funtoo Linux [[Portage Tree]]. Others work on projects in their own repositories and make periodic contributions to Funtoo Linux.
{{#ask: [[Category:People]] [[Role type::Contributor]]
| ? Full name
| ? Nick
| ? Role desc
| ? Start date
| format=template
| template=TeamList
| link=none
}}

=== Former Contributors ===

* [[User:Ferdy|Giuseppe Miceli]] - ''ferdy'' - new
* [[User:Apple|Daniel Cordero]] - ''TheAppleMan''
* [[User:Brantgurga|Brant Gurganus]] - ''brantgurga''
* [[User:destroyFX|Mathieu Bélanger]] - ''destroyFX''
* [https://github.com/hollow Benedikt Böhm] = ''hollow'' - Metro contributor
* [[User:Tarsius|Jonas Bernoulli]] - ''tarsius''
* [[User:Vroman|Víctor Román Archidona]] - ''vroman''
* [[User:Stagr.lee|Lee Thompson]] - ''Stagr.Lee'' - Vagrant/VeeWee hacking
* [[User:404_Error|Adrien Dessemond]] - ''404_Error'' - Funtoo SPARC (since epoch 1296959908)

__NOTITLE__

[[Category:Community]]

Category:People

2012-11-18T20:24:56Z

Palica:

[[Has default form::Person|:Person]]

[[Category:Community]]

Core Team Responsibilities

2012-11-18T20:24:40Z

Palica: /* Seniority */

There are responsibilities associated with being an active Funtoo Linux Core Team member. These responsibilities are detailed below.

=== The Vision ===

* '''The [[Funtoo Linux Vision]] defines our focus and direction.

All Core Team members are expected to agree with and support the [[Funtoo Linux Vision]], and to actively participate in pursuing this vision every week.

=== Metro ===

* '''Reliable automated builds are a priority of the Funtoo Linux project.'''

Active Funtoo Linux Core Team members must use Metro to regularly build Funtoo Linux stages. Every Core Team member must perform a full stage1/2/3 build at least once a week. This may be automated via cron job. Core Team members must be aware of any build failures that occur and communicate them to the rest of the team, and take steps to ensure they are resolved.

=== Install Testing ===

* '''A trouble-free installation experience is a priority of the Funtoo Linux project.'''
* '''The initial end-user experience is important.'''

Active Funtoo Linux Core Team members must perform a fresh install of Funtoo Linux from current stage3 at least once per calendar month. This install may be in a virtual machine, or to replace an existing install. During this install process, any bugs or anomalies must be documented on the [[Usability Testing]] page, reported to the rest of the team, and steps should be taken by the developer to address any problems found.

The Core Team Lead may assign "install weeks" to particular developers to ensure that Funtoo Linux installation is tested as frequently as possible.

=== Team Size ===

Currently, the Core Team is defined to be ''five'' people in size.

=== Availability ===

* '''Excellent user support and timely resolution of problems is a priority of the Funtoo Linux project.'''
* '''Core Team members are there to keep Funtoo Linux working well for its users.'''

A Funtoo Core Team member maintains "active" status by being available for consecutive week-long periods to perform active development, fix bugs and participate in the #funtoo development channel, forums or funtoo-dev mailing list. A developer does not need to be available on a particular day, but must be available and active for at least 4 days per week, and should be able to perform at least 1 hour of active, focused development per day.

If you do not think that you can commit to this level of involvement, you should become a [[Core Team#Contributor|Funtoo Linux Contributor]] instead. Core Team members bear the primary responsibility for being available to resolve QA issues in a timely manner and move various key distribution initiatives forward, so our contribution and availability requirements for Core Team members are quite stringent.

==== Absences ====

Week-long absences are permitted as long as they are announced in advance to <tt>staff@funtoo.org</tt> so that adequate Core Team coverage for any particular week can be assured. Any absence longer than a week (7 days) in duration should be announced in advance as well, but will result in the developer moving from the role of active Core Team member to a Contributor position in their absence.

==== Reinstatements ====

Core Team members that are unavailable and move to a Contributor role due to their absence may be reinstated as members of the Core Team when they are available to return to active duty, at the discretion of the Development Lead. However, there will be a limited number of "seats" available on the Core Team, and empty positions may be filled.

The Core Team Lead may decide to expand the size of the Core Team, but this is not a requirement.

This policy exists to provide an incentive for Core Team members to remain continually active on the project. This policy is also designed to accommodate certain realities of Free Software projects: often, we have a contributor who is active for several months and makes many valuable contributions to Funtoo Linux, but then they become inactive.

If we keep this person as a Core Team member indefinitely, it has the potential of negatively impacting the quality of Funtoo Linux and preventing others who ''are'' available from actively contributing to Funtoo Linux. This policy helps Funtoo Linux adapt to the realities of volunteer contribution.

==== Seniority ====

These policies define the standard policies that apply to all Core Team members. However, those who have a consistent track record of contribution to the Core Team and have made a significant investment in the quality and capabilities of Funtoo Linux may be afforded exceptions to some of these policies.

For example, long-term Core Team members may be able to take more extended periods of absence and still retain their original position when they return. The intention of these seniority exceptions is to provide some benefit and security to those who have made a significant contribution to the project, and also provide a goal for newer Core Team members to aspire to. We want to reward those who have been there for us.

[[Category:Community]]

Category:Community

2012-11-18T20:24:29Z

Palica: Created page with "Category:Funtoo"

[[Category:Funtoo]]

Core Team Lead

2012-11-18T20:24:14Z

Palica:

The Core Team Lead (effectively the day-to-day leader of the project) is now a rotating position, with 3-month to 6-month terms, and all Core Team members are expected to serve in this capacity at some point (dates are flexible.) The acting Core Team Lead will have the opportunity and responsibility to provide leadership for the project, and help the project pursue initiatives that he/she finds personally interesting or is passionate about and are in line with the general goals of the project.

The Core Team Lead will also coordinate closely with Daniel Robbins regarding project direction and BDFL initiatives, and keep in close communication with the rest of the Core Team. The other Core Team members are responsible to assist the Core Team Lead in pursuing these initiatives, just as the Core Team Lead is responsible to support Core Team members in their day-to-day development and support activities. The Core Team Lead will also be engaged with end users and be responsible for leading the effort in fixing build breaks and other critical bugs, along with Daniel Robbins and with the support of the Core Team. ''A key aspect of the Core Team Lead position is to ensure that coordination, communication and execution of important tasks are happening in an effective way, throughout the entire Funtoo Community (Users, Contributors, Core Team and BDFL.)''

The Core Team Lead position is designed to share the opportunity and responsibility of running the project fairly, among all team members, and it is a great opportunity for Core Team members to grow in their skills and abilities.

[[Category:Community]]

Clang

2012-11-18T20:21:10Z

Palica: /* Using clang with distcc */

==Introduction==
LLVM can be used as an alternative to GNU's compiler, GCC. The main benefit of using LLVM compilers instead of GCC is their lower memory usage, faster compile time and better diagnostics. There are some Benchmarks on the [http://clang.llvm.org/features.html#performance Clang] and [http://www.phoronix.com/scan.php?page=article&item=llvm3_gcc_open64 Phoronix] homepages.

It may happen that some programs do not compile (like glibc) because they depend on GCC-specific language extensions [http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html] (this is why the whole BSD code can be compiled with LLVM but some GNU code cannot) or segfault after successful compilation with LLVM (like xorg-server) but after following this guide, the system will still be able to compile packages with gcc. So if something goes wrong, it can be switched back to gcc for the particular package by uncommenting lines in /etc/make.conf and the bug should be reported.

LLVM's C/C++ frontends clang and clang++ version 3.0 are stable enough to be self-hosting [http://blog.llvm.org/2010/02/clang-successfully-self-hosts.html] and compile Boost [http://blog.llvm.org/2010/05/clang-builds-boost.html], Qt [http://labs.qt.nokia.com/2010/10/29/compiling-qt-with-clang/], LibreOffice [http://wiki.documentfoundation.org/Development/Building_LibreOffice_with_Clang], FreeBSD [http://wiki.freebsd.org/BuildingFreeBSDWithClang], some parts of the Linux kernel [http://lwn.net/Articles/411654/] and more.

Further, using LLVM 3.0 and up, there is a third way to compile with LLVM: the dragonegg package creates a gcc-plugin, that uses LLVM's optimizers but parses the code and creates binaries with gcc, which means that everything that compiles and works with gcc should work with dragonegg also. This plugin can be enabled by using a single CFLAG. Since LLVM 3.0 the old llvm-gcc package is deprecated and replaced by dragonegg, so it will disappear from portage with llvm version 2.9.

==LLVM Frontends==
To be able to compile some sourcecode of a specific language, LLVM needs an appropriate frontend. There are clang, llvm-gcc and dragonegg in portage.

The goal of the Clang project is to create a new C, C++, Objective C and Objective C++ front-end for the LLVM compiler.

llvm-gcc is a modified version of gcc that compiles C/ObjC programs into native objects, LLVM bitcode or LLVM assembly language, depending upon the options. As written in the previous section, dragonegg replaced llvm-gcc in version 3.0.

So after installing llvm, clang and dragonegg, you will be able to choose between gcc and llvm whenever you like or use them both at the same time.

== Install LLVM and it's Frontends ==
Simply emerge the packages on ~arch systems. On arch systems you have to unmask some packages first. dragonegg requires gcc's ''lto'' USE-flag to be set and works with gcc 4.5 and gcc 4.6.

{{Root|emerge llvm clang dragonegg}}

Note, that for clang++ the C++ headers search path is hardcoded to the active gcc profile.
If you change the active gcc profile, or update gcc to a new version, you will have to remerge clang to update the search path.

To use dragonegg, run gcc as usual, with an extra command line argument "-fplugin=/usr/lib/llvm/dragonegg.so"
If you change the active gcc profile, or update gcc to a new version, you will have to remerge dragonegg to update the plugin.

After the installation, check which CPUs are supported by using the command
<pre>llvm-as < /dev/null | llc -mcpu=help</pre>
and then add the following lines to /etc/make.conf (uncommenting the lines you need) to enable compilation via LLVM, adapting the march-option according to the previous command:

in /etc/make.conf :
<pre>
# LLVM
#CC="/usr/bin/clang"
#CXX="/usr/bin/clang++"

# llvm-gcc for C++ code and fortran
# llvm-gcc is deprecated and only used with LLVM 2.9
#CC="/usr/bin/llvm-gcc"
#CXX="/usr/bin/llvm-g++"
#CPP="/usr/bin/llvm-cpp"
#F77="/usr/bin/llvm-gfortran"

# Flags for clang: Insert your arch here instead of k8 and have a look at the manpage of clang for flag descriptions.
# Some gcc flags like -pipe and -pthread also work, though they might be ignored by clang.
#CFLAGS="-march=k8 -O2"

# Flags for dragonegg; just use all the gcc flags you like and append -fplugin=/path/to/dragonegg.so
#CFLAGS="-march=k8 -O2 -fplugin=/usr/lib64/llvm/dragonegg.so"
</pre>

Have a look at clang's manpages for additional information. If you get errors that your compiler cannot produce code, you should check your flags, e.g. don't use -O4 -flto -S or stuff like that; the examples above will work.

== Using clang with portage ==

Although Gentoo package tree is not designed to be used with compiler other than GCC, clang can be enforced on most of the packages through ''CC'' and ''CXX'' variables.

Please note, however, that many of Gentoo packages still don't build with clang and a few don't work correctly after being built. That's why we suggest using ''/etc/portage/env'' file to enable the use of clang per-package.

In order to do that, first create a new environment override to use:

in /etc/portage/env/clang :
<pre>
CC=clang
CXX=clang++
</pre>

Then you can enable use of clang for packages using ''[[:/etc/portage/env|/etc/portage/package.env]]'' file:

in /etc/portage/package.env
<pre>
app-foo/bar clang
app-bar/baz clang
</pre>

If you want to use clang by default you can and need specify some core packages. Here is small list of core packages that currently failing on clang, but not that could be outdated:

You need to add /etc/portage/env/gcc :
<pre>
CC=gcc
CXX=g++
</pre>

if addition I recommend to add compiler flags there
<pre>
CFLAGS="-O2 -march=native -mtune=native -pipe"
CXXFLAGS="-O2 -march=native -mtune=native -pipe"
LDFLAGS="-Wl,--as-needed"
#You can disable gold link here
#EXTRA_ECONF="--enable-gold=default"
</pre>

And in /etc/portage/package.env
<pre>
#---------------CORE PACKAGES TO BUILD WITH GCC:
sys-apps/which gcc
sys-fs/reiserfsprogs gcc
sys-libs/ncurses gcc
sys-libs/zlib gcc
sys-apps/busybox gcc
sys-fs/e2fsprogs gcc
sys-devel/binutils gcc
sys-libs/glibc gcc
sys-devel/dragonegg gcc
dev-libs/openssl gcc
sys-boot/grub gcc
#---------------USER PACKAGES TO BUILD WITH GCC:
sys-apps/pacman gcc
www-client/firefox gcc
x11-libs/cairo gcc
media-libs/mesa gcc
</pre>

If you have app-portage/flaggie installed, the ''/etc/portage/package.env'' file could be modified using:

{{Root|flaggie app-foo/bar app-bar/baz +clang}}

== Enabling link-time optimizations ==

The ''link-time optimization'' feature defers optimizing the resulting executables to linking phase. This can result in better optimization of packages but is unsupported in Gentoo yet, and many packages simply fail to build.

When using LTO, clang compiles units into LLVM byte-code rather than machine code. In order to support linking such object files, the [[gold]] linker must be installed and set as the default linker, as it does support plugins.

Similarly, ''ar'' needs plugin support as well. Sadly, binutils ar doesn't support passing '--plugin'' option before the actual command. Thus, we need to create a wrapper for it:

in /usr/local/bin/clang-ar:
<pre>
#!/bin/sh
firstarg=${1}
shift

exec /usr/bin/ar "${firstarg}" --plugin /usr/lib/llvm/LLVMgold.so "${@}"
</pre>

If that's done, you can create a new environment override profile for LTO-enabled clang:

in /etc/portage/env/clang-lt:
<pre>
CC='clang'
CXX='clang++'
CFLAGS="${CFLAGS} -O4"
CXXFLAGS="${CXXFLAGS} -O4"
LDFLAGS="${LDFLAGS} -O4 -Wl,-plugin,/usr/lib/llvm/LLVMgold.so"
AR='/usr/local/bin/clang-ar'
RANLIB=':'
NM='nm --plugin /usr/lib64/llvm/LLVMgold.so'
</pre>

Note that the link-time optimizations were indirectly enabled here via ''-O4''. If you don't want to enable other optimizations enforced by ''-O3'', please use ''-flto'' instead. You need to also pass optimization flags when linking because that's where clang needs them.

You may also need to adjust the libdir path to plugin. Newer (live) versions of clang add `-plugin` when linking automatically, so `-Wl,-plugin`… is no longer necessary.

== Using clang with distcc ==

In order to use clang on distcc client, additional symlinks have to be created in ''/usr/lib*/distcc/bin'':

{{Root|ln -s /usr/bin/distcc /usr/lib/distcc/bin/clang
ln -s /usr/bin/distcc /usr/lib/distcc/bin/clang++}}

{{GLW|src=http://en.gentoo-wiki.com/wiki/Llvm}}

[[Category:HOWTO]]

Choose Funtoo

2012-11-18T19:52:19Z

Palica:

== Choose Funtoo! ==

* Funtoo is a true source-based operating system that gives you the freedom to learn, change, and make it better.

* Funtoo is led by Daniel Robbins who has proven himself to have the skills and qualifications to keep improving Funtoo.

* Funtoo is a rolling release distribution which is essentially version-less once installed.

* Since Funtoo is built locally from source it is optimized for your machine, especially if you use an 8-core processor.

* Funtoo's team of core developers are a small tight-knit community which welcomes others to join the development family.

* Do you want to use <tt>$application</tt> but don't care much for <tt>$optional_feature</tt>? With USE flags, you have full control over what you install on your system.

* Major updates such as toolchain upgrades are tested vigorously before they are introduced to the main branch.

[[Category:Funtoo|*]]

Boot livecd ISO from HDD

2012-11-18T19:51:18Z

Palica:

With grub2 you can easily boot livecd image from hard drive.

== General guide ==
This is general example. I will add settings for different livecd's later.

1. Copy the iso image to root folder for simplicity :
<pre>cp /home/user/downloads/systemrescuecd.iso /src.iso</pre>

2. Reboot and when grub2 loads press 'c' for console. Use following commands (tab autocompletion is your friend) :
<pre>loopback loop (hd0,2)/src.iso
linux (loop)/boot/vmlinuz
initrd (loop)/boot/initrd.lz
boot</pre>

[[Category:HOWTO]]

Baselayout (Funtoo)

2012-11-18T19:50:51Z

Palica:

Funtoo Linux has its own baselayout package that defines the base filesystem structure. It contains a device node creation program called '''realdev'''.

[[Category:Internals]]

Category:Tutorial

2012-11-18T19:45:32Z

Palica:

As you already saw we have HOWTOs, these are there for you to get stuff working in an easy way.
These section is more educational, our Tutorials have the AIM to give you knowledge of what you did and why you did it. Enjoy reading them.

[[Category:Documentation]]

Category:QA

2012-11-18T19:45:18Z

Palica:

[[Category:Development]]

Category:Projects

2012-11-18T19:44:48Z

Palica:

Funtoo Linux has several projects in its ecosystem that come together to form the software you download.
; [[Boot-Update]]
: Boot-update is a tool that brings a unified configuration mechanism across all boot loaders.
; [[Baselayout (Funtoo)]]
: Baselayout provides the basic device nodes and filesystem layout.
; [[OpenRC (Funtoo)]]
: Funtoo OpenRC provides system initialization, service management, and network configuration facilities.
; [[Portage (Funtoo)]]
: Portage is the package manager for Funtoo.
; [[Metro]]
: Metro is Funtoo's automated OS release build system.
; [[Keychain]]
: Keychain helps you to manage ssh and GPG keys in a convenient and secure manner. It acts as a front-end to ssh-agent.

[[Category:Development]]

Category:Processor Architectures

2012-11-18T19:44:28Z

Palica:

[[Category:Hardware]]

Category:Portage

2012-11-18T19:43:57Z

Palica:

This category contains pages related to the Portage package manager/ports system.

[[Category:Documentation]]

Category:Labs

2012-11-18T19:43:11Z

Palica:

Funtoo Labs is where Funtoo Research and Development projects can be found. This provides a nice place for you to see what we're working on, and also potentially get involved :)

[[Category:Development]]

Category:HOWTO

2012-11-18T19:42:18Z

Palica:

You can do many things with Funtoo Linux. This is just a sample of how to do some tasks.

'''Note to Authors:''' The HOWTO section is for short, to the point, hands-on guides. Guides that also delve into the ''why'' in addition to the ''how'' belong in [[:Category:Tutorial]].

[[Category:Documentation]]

Category:Desktop

2012-11-18T19:41:34Z

Palica:

This page lists all desktop-related pages, such as window managers and desktop environments (DE).

[[Category:Software]]

Category:HWLaptop

2012-11-18T19:40:39Z

Palica:

This Category will keep track of special setups for different laptop hardware setups. Please specify the setup you used in an own page and set the category as HWLaptop.

[[Category:Hardware]]

Category:Hardware Compatibility

2012-11-18T19:40:16Z

Palica:

This category is used to tag pages that provide information about the compatibility of hardware with Funtoo Linux.

[[Category:Hardware]]

Category:Articles

2012-11-18T19:39:52Z

Palica:

Most of these articles began their lives on IBM developerWorks, in Daniel's "Common Threads" column. They have now been wiki-fied, so they can be maintained into the future. Enjoy them, and help us maintain them!

[[Category:Documentation]]

Category:Internals

2012-11-18T19:39:19Z

Palica:

There are a lot of packages that go into Funtoo. The items in this category take a deep dive into some of them and how they affect the operation of Funtoo Linux.

[[Category:Development]]

Category:Development

2012-11-18T19:38:58Z

Palica:

[[Category:Funtoo]]

Category:Software

2012-11-18T19:37:55Z

Palica: Created page with "This is the Software category. Category:Funtoo"

This is the Software category.

[[Category:Funtoo]]

Category:Hardware

2012-11-18T19:36:33Z

Palica: Created page with "This is the Hardware category. Category:Funtoo"

This is the Hardware category.

[[Category:Funtoo]]