Difference between pages "Keychain" and "Funtoo Linux FAQ"

From Funtoo
(Difference between pages)
Jump to: navigation, search
(GPG)
 
(How do I update my git-based Portage tree?)
 
Line 1: Line 1:
== Introduction ==
+
== Common Misconceptions, Rumors, etc. ==
  
<tt>Keychain</tt> helps you to manage ssh and GPG keys in a convenient and secure manner. It acts as a frontend to <tt>ssh-agent</tt> and <tt>ssh-add</tt>, but allows you to easily have one long running <tt>ssh-agent</tt> process per system, rather than the norm of one <tt>ssh-agent</tt> per login session.
+
=== Does Funtoo Linux use a Red Hat kernel? ===
  
This dramatically reduces the number of times you need to enter your passphrase. With <tt>keychain</tt>, you only need to enter a passphrase once every time your local machine is rebooted. <tt>Keychain</tt> also makes it easy for remote cron jobs to securely &quot;hook in&quot; to a long running <tt>ssh-agent</tt> process, allowing your scripts to take advantage of key-based logins.
+
Funtoo Linux users are free to choose their own kernel, just like in Gentoo Linux, although RHEL kernel compatibility is a priority of this project, so that enterprise users have the option of using
 +
such kernels. We maintain instructions for how to get a RHEL5-based kernel running under Funtoo Linux, and also ensure that this option is officially supported. See [[RHEL5 Kernel HOWTO]].
  
== Download and Resources ==
+
=== Does Funtoo use an overlay? ===
  
The latest release of keychain is version <tt>2.7.1</tt>, and was released on May 7, 2010. The current version of keychain supports <tt>gpg-agent</tt> as well as <tt>ssh-agent</tt>.
+
Yes and no. We do have an overlay at [http://www.github.com/funtoo/funtoo-overlay GitHub] that contains all the Funtoo modifications to Gentoo. However, the overlay is intended for developers, and users should use our integrated git-based Portage trees with all the overlay changes merged in. The reason for this is that our integrated Portage trees also have profile patches applied, which are stored within our overlay at funtoo/patches, if you want to check them out. So if you just use our overlay on top of the Gentoo tree, it will not work properly.
  
Keychain is compatible with many operating systems, including <tt>AIX</tt>, <tt>*BSD</tt>, <tt>Cygwin</tt>, <tt>MacOS X</tt>, <tt>Linux</tt>, <tt>HP/UX</tt>, <tt>Tru64 UNIX</tt>, <tt>IRIX</tt>, <tt>Solaris</tt> and <tt>GNU Hurd</tt>.
+
=== Is there a lot of junk in your Portage tree? ===
  
=== Download ===
+
No. At one point, we had a lot of overlays merged in to our Portage tree, such as the sunrise overlay. We now have a very clean Portage tree, and sunrise is no longer part of the tree. All Funtoo changes to the tree can be found in our overlay at [http://www.github.com/funtoo/funtoo-overlay GitHub]. All other changes come from Gentoo and a few other overlays (see [[Portage Tree]].) Funtoo Linux changes are very well-maintained and organized in our overlay.
  
* ''Release Archive''
+
== Using Funtoo Linux, Portage and Git ==
** [http://www.funtoo.org/archive/keychain/keychain-2.7.1.tar.bz2 keychain 2.7.1]
+
  
* ''Apple MacOS X Packages''
+
=== How do I start using Funtoo Linux? ===
** [http://www.funtoo.org/archive/keychain/keychain-2.7.1-macosx.tar.gz keychain 2.7.1 MacOS X package]
+
  
 +
For information on how to start using Funtoo Linux, see the [[Funtoo Linux Quick Install Guide]].
  
Keychain development sources can be found in the [http://www.github.com/funtoo/keychain keychain git repository]. Please use the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and [irc://irc.freenode.net/funtoo #funtoo irc channel] for keychain support questions as well as bug reports.
+
=== Is it possible to convert an existing Gentoo Linux install to Funtoo Linux? ===
  
== Quick Setup ==
+
Yes, it is possible, but I am no longer supporting this method as it can be problematic and is always sub-optimal to installing Funtoo Linux from a stage3.
  
=== Linux ===
+
=== I can't use <tt>emerge --sync</tt> to download an initial Portage tree. ===
 +
 
 +
Make sure you have the following in /etc/make.conf
 +
<pre>
 +
SYNC="git://github.com/funtoo/ports-2012.git"
 +
</pre>
 +
 
 +
Note: Recent versions of portage (>=sys-apps/portage-2.3) should not require hard-coded SYNC variables. In fact, after you have synced and updated to a recent portage, you should remove the SYNC line from your make.conf. This will ease your future maintenance when older portage trees are retired.
 +
 
 +
=== I try to emerge something and Portage complains that a digest is not found. ===
 +
 
 +
You are using a Funtoo mini-manifest tree and forgot to enable mini-manifest. To do this, add the following to <tt>/etc/make.conf</tt>:
 +
 
 +
<pre>FEATURES=&quot;mini-manifest&quot;</pre>
 +
=== What is mini-manifest? ===
 +
 
 +
Funtoo's default Portage tree has gone on a diet - Manifests now include only entries for distfiles (source tarballs.) For everything else, we rely on git's internal integrity-checking mechanisms which is based on SHA1 digests.
 +
 
 +
In addition, our mini-Portage tree does not include ChangeLogs for additional space savings. This allows us to offer a Portage tree snapshot that is under 30MB in size when compressed.
 +
 
 +
=== How do I update my git-based Portage tree? ===
 +
 
 +
If you already have an existing git-based Portage tree, you can update it by typing:
  
To install under Gentoo or Funtoo Linux, type
 
 
<console>
 
<console>
###i## emerge keychain
+
###i## emerge --sync
</console>. For other Linux distributions, use your distribution's package manager, or download and install using the source tarball above. Then generate RSA/DSA keys if necessary. The quick install docs assume you have a DSA key pair named <tt>id_dsa</tt> and <tt>id_dsa.pub</tt> in your <tt>~/.ssh/</tt> directory. Add the following to your <tt>~/.bash_profile</tt>:
+
</console>
{{File
+
|~/.bash_profile|<pre>
+
eval `keychain --eval --agents ssh id_rsa`
+
</pre>}}
+
If you want to take advantage of GPG functionality, ensure that GNU Privacy Guard is installed and omit the <tt>--agents ssh</tt> option above.
+
  
=== Apple MacOS X ===
+
=== I set up my initial git-based Portage tree, but <tt>/usr/portage</tt> seems to be empty. ===
  
To install under MacOS X, install the MacOS X package for keychain. Assuming you have an <tt>id_dsa</tt> and <tt>id_dsa.pub</tt> key pair in your <tt>~/.ssh/</tt> directory, add the following to your <tt>~/.bash_profile</tt>:
+
You forgot to type:
  
{{File
+
<pre># cd /usr/portage
|~/.bash_profile|<pre>
+
# git checkout funtoo.org</pre>
eval `keychain --eval --agents ssh --inherit any id_dsa`
+
Funtoo Linux's portage tree snapshot ships with a mostly empty branch active by default to reduce the size of the resultant snapshot tarball.
</pre>}}
+
{{Note}}The <tt>--inherit any</tt> option above causes keychain to inherit any ssh key passphrases stored in your Apple MacOS Keychain. If you would prefer for this to not happen, then this option can be omitted.
+
  
== Background ==
+
=== What is different with Funtoo's UTF-8 support? ===
  
You're probably familiar with <tt>ssh</tt>, which has become a secure replacement for the venerable <tt>telnet</tt> and <tt>rsh</tt> commands.
+
Funtoo Linux has UTF-8 enabled by default, even for the <tt>root</tt> user. This allows UTF-8 files to be edited without issue, <tt>root</tt> GNU screen sessions to display UTF-8 character sets properly, etc. The classic sort order of <tt>ls -a</tt> has been preserved by setting <tt>LC_COLLATE</tt> to <tt>POSIX</tt>. All other locale settings inherit the system default defined in the <tt>LANG</tt> variable, which is set to <tt>en_US.UTF-8</tt>.
  
Typically, when one uses <tt>ssh</tt> to connect to a remote system, one supplies a secret passphrase to <tt>ssh</tt>, which is then passed in encrypted form over the network to the remote server. This passphrase is used by the remote <tt>sshd</tt> server to determine if you should be granted access to the system.
+
=== What if I want to use a non-English locale/language? ===
  
However, `OpenSSH` and nearly all other SSH clients and servers have the ability to perform another type of authentication, called asymmetric public key authentication, using the RSA or DSA authentication algorithms. They are very useful, but can also be complicated to use. <tt>keychain</tt> has been designed to make it easy to take advantage of the benefits of RSA and DSA authentication.
+
I recommend two things. First, it's strongly recommended that you always use a UTF-8-based locale.
  
== Generating a Key Pair ==
+
The next thing I recommend is to try to avoid changing the global system LANG setting, and instead set the LANG setting on a per-user basis by adding the desired LANG setting to your <tt>~/.bashrc</tt>. This will preserve English log output in <tt>/var/log</tt> and make it easier to search for more common matching English strings on the Internet when you need help.
  
To use RSA and DSA authentication, first you use a program called <tt>ssh-keygen</tt> (included with OpenSSH) to generate a ''key pair'' -- two small files. One of the files is the ''public key''. The other small file contains the ''private key''. <tt>ssh-keygen</tt> will ask you for a passphrase, and this passphrase will be used to encrypt your private key. You will need to supply this passphrase to use your private key. If you wanted to generate a DSA key pair, you would do this:
+
If you really want to change the default system LANG setting (taking into account the paragraph above,) then it's recommended that you create your own <tt>/etc/env.d/02locale</tt> file that contains something like this:
  
<console># ##i##ssh-keygen -t dsa
+
<pre>LANG=&quot;fr_CA.UTF-8&quot;</pre>
Generating public/private dsa key pair.</console>
+
You will need to run <tt>etc-update</tt> and <tt>source /etc/profile</tt> to apply changes immediately to any open shells, and reboot to apply changes fully.
You would then be prompted for a location to store your key pair. If you do not have one currently stored in <tt>~/.ssh</tt>, it is fine to accept the default location:
+
  
<console>Enter file in which to save the key (/root/.ssh/id_dsa): </console>
+
=== What is different with Funtoo's Ruby? ===
Then, you are prompted for a passphrase. This passphrase is used to encrypt the ''private key'' on disk, so even if it is stolen, it will be difficult for someone else to use it to successfully authenticate as you with any accounts that have been configured to recognize your public key.
+
  
Note that conversely, if you '''do not''' provide a passphrase for your private key file, then your private key file '''will not''' be encrypted. This means that if someone steals your private key file, ''they will have the full ability to authenticate with any remote accounts that are set up with your public key.''
+
Funtoo Linux tracks Gentoo's Ruby, but we do have one change for ruby-1.9 and greater - the binary name is changed with /usr/bin/ruby1.9 instead of Gentoo's /usr/bin/ruby19. This makes the versioning consistent with Python binaries and MacOS X. This means that for ruby-1.9 and greater. While the path to the binary has changed, all Portage variables are the same as Gentoo, so you should use &quot;ruby19&quot; for the <tt>RUBY_TARGETS</tt> setting in <tt>/etc/make.conf</tt>.
  
Below, I have supplied a passphrase so that my private key file will be encrypted on disk:
+
=== Ruby 1.9 is masked. How do I use it? ===
  
<console>Enter passphrase (empty for no passphrase): ##i#########
+
Add the following to /etc/make.conf:
Enter same passphrase again: ##i#########
+
Your identification has been saved in /var/tmp/id_dsa.
+
Your public key has been saved in /var/tmp/id_dsa.pub.
+
The key fingerprint is:
+
5c:13:ff:46:7d:b3:bf:0e:37:1e:5e:8c:7b:a3:88:f4 root@devbox-ve
+
The key's randomart image is:
+
+--[ DSA 1024]----+
+
|          .      |
+
|          o  . |
+
|          o . ..o|
+
|      . . . o  +|
+
|        S    o. |
+
|            . o.|
+
|        .  ..++|
+
|        . o . =o*|
+
|        . E .+*.|
+
+-----------------+</console>
+
  
== Setting up Authentication ==
+
<pre>RUBY_TARGETS=&quot;ruby19&quot;</pre>
 +
Then unmask ruby-1.9 as follows:
  
Here's how you use these files to authenticate with a remote server. On the remote server, you would append the contents of your ''public key'' to the <tt>~.ssh/authorized_keys</tt> file, if such a file exists. If it doesn't exist, you can simply create a new <tt>authorized_keys</tt> file in the remote account's <tt>~/.ssh</tt> directory that contains the contents of your local <tt>id_dsa.pub</tt> file.
+
<pre># install -d /etc/portage
 +
# echo &quot;dev-lang/ruby:1.9&quot; &gt;&gt; /etc/portage/package.unmask</pre>
 +
If you are using Funtoo stable, then you will also need to do this:
  
Then, if you weren't going to use <tt>keychain</tt>, you'd perform the following steps. On your local client, you would start a program called <tt>ssh-agent</tt>, which runs in the background. Then you would use a program called <tt>ssh-add</tt> to tell <tt>ssh-agent</tt> about your secret private key. Then, if you've set up your environment properly, the next time you run <tt>ssh</tt>, it will find <tt>ssh-agent</tt> running, grab the private key that you added to <tt>ssh-agent</tt> using <tt>ssh-add</tt>, and use this key to authenticate with the remote server.
+
<pre># echo &quot;dev-lang/ruby:1.9&quot; &gt;&gt; /etc/portage/package.keywords</pre>
  
Again, the steps in the previous paragraph is what you'd do if <tt>keychain</tt> wasn't around to help. If you are using <tt>keychain</tt>, and I hope you are, you would simply add the following line to your <tt>~/.bash_profile</tt> or if a regular user to<tt>~/.bashrc</tt> :
+
=== Why is Funtoo Linux still an older udev? ===
  
{{File
+
Funtoo Linux currently uses udev-160 and generally updates udev less frequently than in Gentoo Linux.
|~/.bash_profile|<pre>
+
eval `keychain --eval id_dsa`
+
</pre>}}
+
The next time you log in or source your <tt>~/.bash_profile</tt> or if you use <tt>~/.bashrc</tt>, <tt>keychain</tt> will start, start <tt>ssh-agent</tt> for you if it has not yet been started, use <tt>ssh-add</tt> to add your <tt>id_dsa</tt> private key file to <tt>ssh-agent</tt>, and set up your shell environment so that <tt>ssh</tt> will be able to find <tt>ssh-agent</tt>. If <tt>ssh-agent</tt> is already running, <tt>keychain</tt> will ensure that your <tt>id_dsa</tt> private key has been added to <tt>ssh-agent</tt> and then set up your environment so that <tt>ssh</tt> can find the already-running <tt>ssh-agent</tt>. It will look something like this:
+
  
Note that when <tt>keychain</tt> runs for the first time after your local system has booted, you will be prompted for a passphrase for your private key file if it is encrypted. But here's the nice thing about using <tt>keychain</tt> -- even if you are using an encrypted private key file, you will only need to enter your passphrase when your system first boots (or in the case of a server, when you first log in.) After that, <tt>ssh-agent</tt> is already running and has your decrypted private key cached in memory. So if you open a new shell, you will see something like this:
+
=== What is the minimum kernel version I can use with Funtoo Linux? ===
  
This means that you can now <tt>ssh</tt> to your heart's content, without supplying a passphrase.
+
Without making changes to the default version of the udev package, Funtoo Linux is compatible with kernel versions 2.6.27 and greater. To use earlier kernels or enterprise kernels, see below.
  
You can also execute batch <tt>cron</tt> jobs and scripts that need to use <tt>ssh</tt> or <tt>scp</tt>, and they can take advantage of passwordless RSA/DSA authentication as well. To do this, you would add the following line to the top of a bash script:
+
=== I need to use a kernel earlier than 2.6.27. What should I do? ===
  
{{File
+
To use a RHEL5 or RHEL5-based kernel, you will need to use udev-146 or earlier. Funtoo Linux provides these versions in its portage tree. All you need to do is add the following line to <tt>/etc/portage/package.mask</tt>:
|~/.bash_profile|<pre>
+
eval `keychain --noask --eval id_dsa` || exit 1
+
</pre>}}
+
The extra <tt>--noask</tt> option tells <tt>keychain</tt> that it should not prompt for a passphrase if one is needed. Since it is not running interactively, it is better for the script to fail if the decrypted private key isn't cached in memory via <tt>ssh-agent</tt>.
+
  
== Keychain Options ==
+
<pre>&gt;=sys-fs/udev-160</pre>
 +
Then, emerge udev:
  
=== Specifying Agents ===
+
<pre>emerge udev</pre>
  
In the images above, you will note that <tt>keychain</tt> starts <tt>ssh-agent</tt>, but also starts <tt>gpg-agent</tt>. Modern versions of <tt>keychain</tt> also support caching decrypted GPG keys via use of <tt>gpg-agent</tt>, and will start <tt>gpg-agent</tt> by default if it is available on your system. To avoid this behavior and only start <tt>ssh-agent</tt>, modify your <tt>~/.bash_profile</tt> as follows:
+
You can now reboot with a RHEL5-based kernel and udev will still work properly. <tt>udev-135</tt> is also available for even earlier kernels.
  
{{File
+
=== How do I use a RHEL5-based kernel, such as openvz-sources-2.6.18* with Funtoo? ===
|~/.bash_profile|<pre>
+
eval `keychain --agents ssh --eval id_dsa` || exit 1
+
</pre>}}
+
The additional <tt>--agents ssh</tt> option tells <tt>keychain</tt> just to manage <tt>ssh-agent</tt>, and ignore <tt>gpg-agent</tt> even if it is available.
+
  
=== Clearing Keys ===
+
The steps required to do this, including downgrading udev and emerging gcc-4.1.2, can be found in the [[RHEL5 Kernel HOWTO]]
  
Sometimes, it might be necessary to flush all cached keys in memory. To do this, type:
+
=== Why is package.mask a directory? ===
  
<console># ##i##keychain --clear</console>
+
I decided to convert <tt>/usr/portage/profiles/package.mask</tt> to a directory as soon as I discovered that this was a supported feature in the current Portage. This allows us to maintain package.mask data more effectively.
Any agent(s) will continue to run.
+
  
=== Improving Security ===
+
=== Git complains and aborts when I emerge --sync. ===
  
To improve the security of <tt>keychain</tt>, some people add the <tt>--clear</tt> option to their <tt>~/.bash_profile</tt> <tt>keychain</tt> invocation. The rationale behind this is that any user logging in should be assumed to be an intruder until proven otherwise. This means that you will need to re-enter any passphrases when you log in, but cron jobs will still be able to run when you log out.
+
It appears that a previous git merge was interrupted or did not complete, leaving your portage tree in an intermediate state. Typically, this can be fixed by typing:
  
=== Stopping Agents ===
+
<pre># cd /usr/portage
 +
# git reset --hard origin/funtoo.org</pre>
 +
This should restore your portage tree to a consistent state and allow future <tt>emerge --sync</tt> commands to complete successfully.
  
If you want to stop all agents, which will also of course cause your keys/identities to be flushed from memory, you can do this as follows:
+
If this doesn't work, then you may have a conflicted merge. Maybe you modified some local ebuilds? To view conflicts, type <tt>git diff --stat</tt> from within the <tt>/usr/portage</tt> directory. You can choose to either resolve these conflicts or revert back to the official Funtoo Portage tree.
  
<console># ##i##keychain -k all</console>
+
If you want to throw away your local changes and simply use the Funtoo Portage tree, you'll need to remove all the files in <tt>/usr/portage</tt> besides the <tt>.git</tt> directory, and then trying the <tt>git reset --hard origin/funtoo.org</tt> command again, as follows:
If you have other agents running under your user account, you can also tell <tt>keychain</tt> to just stop only the agents that <tt>keychain</tt> started:
+
  
<console># ##i##keychain -k mine</console>
+
<pre># cd /usr/portage
 +
# mv distfiles ..
 +
# rm -rf * .gitignore
 +
# git reset --hard origin/funtoo.org
 +
# mv ../distfiles .</pre>
 +
Now everything should be working again.
  
== GPG ==
+
=== How do I tell if a problem I am having originates from Gentoo or Funtoo? ===
  
Keychain can ask you for your GPG passphrase if you provide it the GPG key ID. To find it out:
+
You can tell if there are any Funtoo changes to an ebuild by browsing the [http://www.github.com/funtoo/funtoo-overlay funtoo-overlay]. All the Funtoo-specific ebuilds can be found in our overlay. If you see an ebuild in my overlay, then we use my version ''instead of'' the Gentoo version. If you don't see it in the funtoo overlay, then it comes from Gentoo.
<console>
+
$##bl## gpg -k
+
pub  2048R/DEADBEEF 2012-08-16
+
uid                  Name (Comment) <email@host.tld>
+
sub  2048R/86D2FAC6 2012-08-16
+
</console>
+
  
Note the '''DEADBEEF''' above is the ID. Then, in your login script, do your usual
+
=== How can I see the differences between the Gentoo and Funtoo Portage trees? ===
  
<console>
+
In the old days, this was tricky, but now you just look at the [http://www.github.com/funtoo/funtoo-overlay funtoo-overlay] for a complete repository of all the Funtoo-specific stuff. Everything ''not'' in the Funtoo overlay comes from Gentoo, with a few exceptions -- see [[Portage Tree]] for details.
$##bl## keychain --dir ~/.ssh/.keychain ~/.ssh/id_rsa DEADBEEF
+
 
$##bl## source ~/.ssh/.keychain/$HOST-sh
+
=== Is Paludis compatible with the Funtoo Portage tree? ===
$##bl##source ~/.ssh/.keychain/$HOST-sh-gpg
+
 
</console>
+
Paludis does not appear to be compatible with the Funtoo Portage tree, unfortunately. It does not support the <tt>package.mask</tt> directory without additional hooks, and also does not support merging device nodes. These features are supported by Portage and we use both of these capabilities. I think that both <tt>package.mask</tt> (and <tt>package.keywords</tt>, etc.) directories are a good idea, and I also think it's a good idea for the package manager to support device nodes, which is particularly useful for the <tt>udev</tt> and <tt>baselayout</tt> ebuilds. Funtoo Linux has separate versions of these packages, and these ebuilds are easier to maintain if device nodes are correctly supported by the package manger, and the <tt>package.mask</tt> directory is a great help to us as well.
 +
 
 +
We could maintain a patched version of Paludis that would be useable with the Funtoo Portage tree, but I don't want to get into the business of supporting a non-standard package manager as the upstream project seems not seem very supportive of getting these compatibility issues resolved, and thus this could turn into a maintenance burden for Funtoo. So I'd rather just not support Paludis for now.
 +
 
 +
=== What about pkgcore? ===
 +
 
 +
Pkgcore is not currently compatible with Funtoo Linux but efforts are under way to resolve this.
 +
 
 +
=== How do I report a bug? ===
 +
 
 +
The best way to report your bug is to describe the issue you are having on the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list]. Another option is to ask for support in the [irc://irc.freenode.net/funtoo #funtoo]. In general, it's best to contact us first about an issue you are having, rather than opening a Gentoo bug report, unless you are quite familiar with the issue and are fairly certain that it is not a Funtoo Linux issue.
 +
 
 +
If you report a bug to Gentoo that may impact Funtoo Linux in some way, please post information about it to the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] so we are aware of the issue.
 +
 
 +
* More informations: [[Reporting Bugs|Guidelines for Reporting Bugs]].
 +
 
 +
=== How do I become a Funtoo developer? ===
 +
 
 +
Funtoo is a personal project of mine, so I'm the only real developer. However, I involve everyone on the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and [irc://irc.freenode.net/funtoo #funtoo] in what I am doing so that patches, feedback, requests, etc. can be shared. My advice is to get involved in the Funtoo community on the mailing list and irc channel.
 +
 
 +
== General Funtoo Stuff ==
 +
 
 +
=== What is funtoo.org? ===
 +
 
 +
Funtoo.org is the online home of Daniel Robbins (me) and is a place to put all my stuff.
 +
 
 +
=== What kind of stuff? ===
 +
 
 +
Well, I have Funtoo Linux, which is a Gentoo Linux variant. Then I have technical articles -- some new, and some updated versions of originals that appeared on IBM developerWorks.
 +
 
 +
Then I have [[Metro]], an operating system build tool, and I have [[Keychain]], which is a tool to help you manage RSA and DSA keys for ssh.
 +
 
 +
So Funtoo is not just Funtoo Linux.
 +
 
 +
=== What is 'Funtoo' all about? And 'Funtoo Linux'? ===
 +
 
 +
<tt>Funtoo</tt> by itself refers to this site, or the larger <tt>Funtoo</tt> project run by Daniel Robbins. That's just a fancy way of saying that <tt>Funtoo</tt> refers to all the stuff I'm doing.
 +
 
 +
''Funtoo Linux'' refers specifically to my variant of Gentoo Linux.
 +
 
 +
If you see me use the phrase <tt>Funtoo Portage tree</tt> or <tt>Funtoo ebuild</tt>, I'm just talking about our separate (and slightly different) Portage tree, or our version of an ebuild.
 +
 
 +
=== What is 'tnufoo'? ===
 +
 
 +
<tt>tnufoo</tt> is <tt>funtoo</tt> rotated 180 degrees vertically.
 +
 
 +
=== How many developers are working on Funtoo Linux? ===
 +
 
 +
Funtoo Linux development is led by Daniel Robbins, along with a [[Core Team]] that also makes significant contributions to Funtoo Linux development and Funtoo infrastructure.
 +
 
 +
=== Is Funtoo Linux a fork of Gentoo Linux? ===
 +
 
 +
It depends on your definition of <tt>fork</tt>. Officially, I am calling Funtoo Linux a <tt>Gentoo Linux variant</tt>, meaning that it is more like another flavor of Gentoo than a fork.
 +
 
 +
We share our changes and bug fixes with the Gentoo project, so Gentoo is free to merge in any of our changes at any time. We also merge in Gentoo's changes every 12 hours.
 +
 
 +
I could officially call Funtoo Linux a fork of Gentoo Linux, but Gentoo could merge most of our changes into Gentoo proper and then what would Funtoo Linux be? It'd be my variant of Gentoo, that's what it'd be. So let's just call it a variant of Gentoo.
 +
 
 +
=== What is the best way to interact with the Funtoo community? ===
 +
 
 +
I recommend joining the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and, if desired, hanging out in the [irc://irc.freenode.net/funtoo #funtoo] on freenode.
 +
 
 +
The [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] as well as the [irc://irc.freenode.net/funtoo #funtoo] are unmoderated, open discussion forums for both Funtoo Linux users and developers. In addition, these are ''also'' the official lists for discussing other Funtoo projects such as [[Metro]] and [[Keychain]].
 +
 
 +
=== What Architectures does Funtoo Linux support? ===
 +
 
 +
While Funtoo Linux can run on any architecture that Gentoo Linux supports, we are only maintaining Funtoo Linux for x86 and amd64 architectures. Adding support for other architectures may require a little bit of unmasking work in our Portage tree -- or not. We're not testing anything but x86 and amd64, so we don't know :)
 +
 
 +
=== How should a developer use package.mask? ===
 +
 
 +
We currently have four files in the package.mask directory -- <tt>gentoo</tt>, <tt>funtoo</tt>, <tt>funtoo-cautionary</tt> and <tt>sunrise</tt>. Gentoo is an almost pristine version of the upstream gentoo package.mask. It differs from gentoo only in that we will remove stuff from it that we no longer want in it, but we don't ''add'' masks to this file. So if there is a mask in <tt>gentoo</tt>, you know it came upstream from Gentoo.
 +
 
 +
<tt>funtoo</tt> is where we place our masks. <tt>funtoo-cautionary</tt> is where we place masks that are designed to shield us from upstream unstable version changes to core packages, since we don't want to simply follow Gentoo unstable -- instead, we want to control when gcc and glibc switch to new versions. <tt>sunrise</tt> contains a bunch of sunrise and other miscellaneous masks from the <tt>mpd</tt> overlays. It is currently sort of our &quot;junk drawer&quot; that we'll get around to cleaning up at some point.
 +
 
 +
=== Do you use the normal Gentoo system profiles? ===
 +
 
 +
I've made some minor changes to the Funtoo Linux <tt>profiles/</tt> directory, and I'll continue to make improvements as time goes on. The most recent change I made (as of 17 Jul 2009) was to add <tt>net-dns/openresolv</tt> to the core system profile. Since Funtoo development focuses primarily on the core system, you can expect our system profiles to be somewhat different from Gentoo's. However, from a user perspective, you use them the same way and we have the same profile names that are in Gentoo.
 +
 
 +
=== Is Funtoo Linux More Stable Than Gentoo Linux? ===
 +
 
 +
That is a hard question to answer directly, as one person's definition of &quot;stable&quot; may be different than another person's, and I do not know how you intend to use Funtoo Linux. So rather than tackle the question head-on, I can give you some additional information that may help you decide:
 +
 
 +
* The goal of Funtoo Linux is to allow me to improve the Gentoo core system and tools. That does mean that I will be periodically changing various parts of Gentoo plumbing from time to time. When I do this, I try to be careful and provide notices of upcoming major changes on the mailing list, Atom feed and on the Web site.
 +
* Both Funtoo Linux and Gentoo Linux have a stable and unstable (<tt>~</tt> - called "current" in Funtoo) tree
 +
* The Funtoo and Gentoo trees are 99% identical. However, there are signficant differences in certain areas, particularly the core system and Perl, Python and Ruby.
 +
* Funtoo and Gentoo trees do have some significant differences for core packages, particularly <tt>openrc</tt>, <tt>baselayout</tt>, <tt>udev</tt> and <tt>lvm2</tt>.
 +
* If it is important to you, Metro is tested daily to ensure that it can build Funtoo Linux (and Gentoo Linux) successfully. However, these builds are not performed in advance of the changes hitting the public git-based Portage tree.
 +
* Any Metro Funtoo Linux build failures found are typically fixed in the Funtoo Portage within 0-1 days. Gentoo build failures are only fixed if they are related to an issue with Metro. So there is very fast response in Funtoo to core system build failures. In Gentoo, this process is not as integrated.
 +
* Funtoo merges in upstream changes from Gentoo Portage every 12 hours.
 +
* I focus on testing the core, non-GUI/non-X system. Sometimes Funtoo will trail behind in udev revisions that cutting-edge desktop users want to run.
 +
* Both Funtoo Linux stable and current have OpenRC, dhcpcd-5 and OpenResolv integrated by default.
 +
* Funtoo Linux current tries to upgrade certain core packages such as <tt>udev</tt>, <tt>gcc</tt> and <tt>glibc</tt> much less frequently and in a more controlled manner than Gentoo unstable. This may or may not be a benefit to you, depending on what you are looking for. Basically, I am trying to offer the package updates of Gentoo Linux unstable without as much of the (too frequent, in my opinion) core system changes that can often cause problems for people.
 +
* The Funtoo receives Gentoo changes once every 12 hours. In contrast, the Gentoo rsync tree receives updates hourly. This means that the changes in the Funtoo tree are compressed into a single monolithic event, whereas the Gentoo tree undergoes more continual, but less signficant, change every hour.
 +
* Significant build-related bugs found by Funtoo that also impact Gentoo Linux are sent upstream to [http://bugs.gentoo.org bugs.gentoo.org].
 +
 
 +
=== Do you use Gentoo's Guide XML for Documentation? ===
 +
 
 +
I originally created Gentoo's Guide XML format (which I originally created for Gentoo) for documentation, and started to transition away from it in favor of [http://docutils.sourceforge.net/rst.html ReStructuredText]. However, now I am trying to support Guide XML ''and'' [http://docutils.sourceforge.net/rst.html ReStructuredText] as they are both useful for different types of things.
 +
 
 +
Many funtoo.org articles and documents are maintained in ReStructuredText format. HTML versions of the ReStructuredText documentation are generated by first converting the <tt>.rst</tt> file to XML using <tt>rst2xml.py</tt> (part of the docutils distribution), and then using XSLT to convert the resultant XML to HTML.
 +
 
 +
To view the plaintext [http://docutils.sourceforge.net/rst.html ReStructuredText] version of a document, append <tt>/index.rst</tt> to any funtoo.org URL. For example, here is the [http://www.funtoo.org/en/funtoo/faq/index.rst ReStructuredText version of this document]
 +
 
 +
=== Are you looking for translators? ===
 +
 
 +
Many kind people have provided translations of the funtoo.org pages, and the old version of the site used to contain these translations. However, after much consideration, I've decided to not provide translated versions of funtoo.org pages, for several reasons:
  
== Learning More ==
+
* Translated documents tend to become out-of-date
 +
* Updating the translated documents is quite a bit of work
 +
* Most people online seem to have at least a basic grasp of English
  
The instructions above will work on any system that uses <tt>bash</tt> as its default shell, such as most Linux systems and Mac OS X.
+
For these reasons, I'm going to focus on improving the quantity and quality of English documentation, and not focus on translations for now.
  
To learn more about the many things that <tt>keychain</tt> can do, including alternate shell support, consult the keychain man page, or type <tt>keychain --help | less</tt> for a full list of command options.
+
== Forking the Portage Tree ==
  
I also recommend you read my original series of articles about [http://www.openssh.com OpenSSH] that I wrote for IBM developerWorks, called <tt>OpenSSH Key Management</tt>. Please note that <tt>keychain</tt> 1.0 was released along with Part 2 of this article, which was written in 2001. <tt>keychain</tt> has changed quite a bit since then. In other words, read these articles for the conceptual and [http://www.openssh.com OpenSSH] information, but consult the <tt>keychain</tt> man page for command-line options and usage instructions :)
+
=== I want to fork the Portage tree. How do I do this? ===
  
* [http://www.ibm.com/developerworks/library/l-keyc.html Common Threads: OpenSSH key management, Part 1] - Understanding RSA/DSA Authentication
+
The old way used to involve forking our huge, complete Portage tree. Currently, the best way to do it involves forking the [http://www.github.com/funtoo/funtoo-overlay funtoo-overlay], which is much smaller, or creating your own overlay. I have scripts that combine the Funtoo overlay and the Gentoo tree to create a unified Portage tree.
* [http://www.ibm.com/developerworks/library/l-keyc2/ Common Threads: OpenSSH key management, Part 2] - Introducing <tt>ssh-agent</tt> and <tt>keychain</tt>
+
* [http://www.ibm.com/developerworks/library/l-keyc3/ Common Threads: OpenSSH key management, Part 3] - Agent forwarding and <tt>keychain</tt> improvements
+
  
As mentioned at the top of the page, <tt>keychain</tt> development sources can be found in the [http://www.github.com/funtoo/keychain keychain git repository]. Please use the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and [irc://irc.freenode.net/funtoo #funtoo irc channel] for keychain support questions as well as bug reports.
+
=== I have forked my own Portage tree. How do I generate metadata for it? ===
  
== Project History ==
+
You should only do this if you are creating a unified Portage tree for distribution to users. Otherwise, it is much more efficient to use an overlay for this purpose.
  
Daniel Robbins originally wrote <tt>keychain</tt> 1.0 through 2.0.3. 1.0 was written around June 2001, and 2.0.3 was released in late August, 2002.
+
First, add <tt>FEATURES=&quot;metadata-transfer&quot;</tt> to your <tt>/etc/make.conf</tt> file. Then type the following commands:
  
After 2.0.3, <tt>keychain</tt> was maintained by various Gentoo developers, including Seth Chandler, Mike Frysinger and Robin H. Johnson, through July 3, 2003.
+
<pre># cd /usr/portage
 +
# egencache --update --jobs=4
 +
# cd metadata/cache
 +
# git add .
 +
# git commit -a</pre>
 +
<tt>egencache</tt> is part of <tt>sys-apps/portage</tt> and was kindly integrated by Zack Medico, Portage maintainer.
  
On April 21, 2004, Aron Griffis committed a major rewrite of <tt>keychain</tt> which was released as 2.2.0. Aron continued to actively maintain and improve <tt>keychain</tt> through October 2006 and the <tt>keychain</tt> 2.6.8 release. He also made a few commits after that date, up through mid-July, 2007. At this point, <tt>keychain</tt> had reached a point of maturity.
+
=== Where can I learn more about <tt>git</tt>? ===
  
In mid-July, 2009, Daniel Robbins migrated Aron's mercurial repository to git and set up a new project page on funtoo.org, and made a few bug fix commits to the git repo that had been collecting in [http://bugs.gentoo.org bugs.gentoo.org]. Daniel continues to maintain <tt>keychain</tt> and supporting documentation on funtoo.org, and plans to make regular maintenance releases of <tt>keychain</tt> as needed.
+
So, you want to learn more about <tt>git</tt>, do you? A collection of excellent git resources is now available on the [[Git Guide]].
  
 
[[Category:HOWTO]]
 
[[Category:HOWTO]]
[[Category:Projects]]
 

Revision as of 21:59, 26 January 2014

Contents

Common Misconceptions, Rumors, etc.

Does Funtoo Linux use a Red Hat kernel?

Funtoo Linux users are free to choose their own kernel, just like in Gentoo Linux, although RHEL kernel compatibility is a priority of this project, so that enterprise users have the option of using such kernels. We maintain instructions for how to get a RHEL5-based kernel running under Funtoo Linux, and also ensure that this option is officially supported. See RHEL5 Kernel HOWTO.

Does Funtoo use an overlay?

Yes and no. We do have an overlay at GitHub that contains all the Funtoo modifications to Gentoo. However, the overlay is intended for developers, and users should use our integrated git-based Portage trees with all the overlay changes merged in. The reason for this is that our integrated Portage trees also have profile patches applied, which are stored within our overlay at funtoo/patches, if you want to check them out. So if you just use our overlay on top of the Gentoo tree, it will not work properly.

Is there a lot of junk in your Portage tree?

No. At one point, we had a lot of overlays merged in to our Portage tree, such as the sunrise overlay. We now have a very clean Portage tree, and sunrise is no longer part of the tree. All Funtoo changes to the tree can be found in our overlay at GitHub. All other changes come from Gentoo and a few other overlays (see Portage Tree.) Funtoo Linux changes are very well-maintained and organized in our overlay.

Using Funtoo Linux, Portage and Git

How do I start using Funtoo Linux?

For information on how to start using Funtoo Linux, see the Funtoo Linux Quick Install Guide.

Is it possible to convert an existing Gentoo Linux install to Funtoo Linux?

Yes, it is possible, but I am no longer supporting this method as it can be problematic and is always sub-optimal to installing Funtoo Linux from a stage3.

I can't use emerge --sync to download an initial Portage tree.

Make sure you have the following in /etc/make.conf

SYNC="git://github.com/funtoo/ports-2012.git"

Note: Recent versions of portage (>=sys-apps/portage-2.3) should not require hard-coded SYNC variables. In fact, after you have synced and updated to a recent portage, you should remove the SYNC line from your make.conf. This will ease your future maintenance when older portage trees are retired.

I try to emerge something and Portage complains that a digest is not found.

You are using a Funtoo mini-manifest tree and forgot to enable mini-manifest. To do this, add the following to /etc/make.conf:

FEATURES="mini-manifest"

What is mini-manifest?

Funtoo's default Portage tree has gone on a diet - Manifests now include only entries for distfiles (source tarballs.) For everything else, we rely on git's internal integrity-checking mechanisms which is based on SHA1 digests.

In addition, our mini-Portage tree does not include ChangeLogs for additional space savings. This allows us to offer a Portage tree snapshot that is under 30MB in size when compressed.

How do I update my git-based Portage tree?

If you already have an existing git-based Portage tree, you can update it by typing:

# emerge --sync

I set up my initial git-based Portage tree, but /usr/portage seems to be empty.

You forgot to type:

# cd /usr/portage
# git checkout funtoo.org

Funtoo Linux's portage tree snapshot ships with a mostly empty branch active by default to reduce the size of the resultant snapshot tarball.

What is different with Funtoo's UTF-8 support?

Funtoo Linux has UTF-8 enabled by default, even for the root user. This allows UTF-8 files to be edited without issue, root GNU screen sessions to display UTF-8 character sets properly, etc. The classic sort order of ls -a has been preserved by setting LC_COLLATE to POSIX. All other locale settings inherit the system default defined in the LANG variable, which is set to en_US.UTF-8.

What if I want to use a non-English locale/language?

I recommend two things. First, it's strongly recommended that you always use a UTF-8-based locale.

The next thing I recommend is to try to avoid changing the global system LANG setting, and instead set the LANG setting on a per-user basis by adding the desired LANG setting to your ~/.bashrc. This will preserve English log output in /var/log and make it easier to search for more common matching English strings on the Internet when you need help.

If you really want to change the default system LANG setting (taking into account the paragraph above,) then it's recommended that you create your own /etc/env.d/02locale file that contains something like this:

LANG="fr_CA.UTF-8"

You will need to run etc-update and source /etc/profile to apply changes immediately to any open shells, and reboot to apply changes fully.

What is different with Funtoo's Ruby?

Funtoo Linux tracks Gentoo's Ruby, but we do have one change for ruby-1.9 and greater - the binary name is changed with /usr/bin/ruby1.9 instead of Gentoo's /usr/bin/ruby19. This makes the versioning consistent with Python binaries and MacOS X. This means that for ruby-1.9 and greater. While the path to the binary has changed, all Portage variables are the same as Gentoo, so you should use "ruby19" for the RUBY_TARGETS setting in /etc/make.conf.

Ruby 1.9 is masked. How do I use it?

Add the following to /etc/make.conf:

RUBY_TARGETS="ruby19"

Then unmask ruby-1.9 as follows:

# install -d /etc/portage
# echo "dev-lang/ruby:1.9" >> /etc/portage/package.unmask

If you are using Funtoo stable, then you will also need to do this:

# echo "dev-lang/ruby:1.9" >> /etc/portage/package.keywords

Why is Funtoo Linux still an older udev?

Funtoo Linux currently uses udev-160 and generally updates udev less frequently than in Gentoo Linux.

What is the minimum kernel version I can use with Funtoo Linux?

Without making changes to the default version of the udev package, Funtoo Linux is compatible with kernel versions 2.6.27 and greater. To use earlier kernels or enterprise kernels, see below.

I need to use a kernel earlier than 2.6.27. What should I do?

To use a RHEL5 or RHEL5-based kernel, you will need to use udev-146 or earlier. Funtoo Linux provides these versions in its portage tree. All you need to do is add the following line to /etc/portage/package.mask:

>=sys-fs/udev-160

Then, emerge udev:

emerge udev

You can now reboot with a RHEL5-based kernel and udev will still work properly. udev-135 is also available for even earlier kernels.

How do I use a RHEL5-based kernel, such as openvz-sources-2.6.18* with Funtoo?

The steps required to do this, including downgrading udev and emerging gcc-4.1.2, can be found in the RHEL5 Kernel HOWTO

Why is package.mask a directory?

I decided to convert /usr/portage/profiles/package.mask to a directory as soon as I discovered that this was a supported feature in the current Portage. This allows us to maintain package.mask data more effectively.

Git complains and aborts when I emerge --sync.

It appears that a previous git merge was interrupted or did not complete, leaving your portage tree in an intermediate state. Typically, this can be fixed by typing:

# cd /usr/portage
# git reset --hard origin/funtoo.org

This should restore your portage tree to a consistent state and allow future emerge --sync commands to complete successfully.

If this doesn't work, then you may have a conflicted merge. Maybe you modified some local ebuilds? To view conflicts, type git diff --stat from within the /usr/portage directory. You can choose to either resolve these conflicts or revert back to the official Funtoo Portage tree.

If you want to throw away your local changes and simply use the Funtoo Portage tree, you'll need to remove all the files in /usr/portage besides the .git directory, and then trying the git reset --hard origin/funtoo.org command again, as follows:

# cd /usr/portage
# mv distfiles ..
# rm -rf * .gitignore
# git reset --hard origin/funtoo.org
# mv ../distfiles .

Now everything should be working again.

How do I tell if a problem I am having originates from Gentoo or Funtoo?

You can tell if there are any Funtoo changes to an ebuild by browsing the funtoo-overlay. All the Funtoo-specific ebuilds can be found in our overlay. If you see an ebuild in my overlay, then we use my version instead of the Gentoo version. If you don't see it in the funtoo overlay, then it comes from Gentoo.

How can I see the differences between the Gentoo and Funtoo Portage trees?

In the old days, this was tricky, but now you just look at the funtoo-overlay for a complete repository of all the Funtoo-specific stuff. Everything not in the Funtoo overlay comes from Gentoo, with a few exceptions -- see Portage Tree for details.

Is Paludis compatible with the Funtoo Portage tree?

Paludis does not appear to be compatible with the Funtoo Portage tree, unfortunately. It does not support the package.mask directory without additional hooks, and also does not support merging device nodes. These features are supported by Portage and we use both of these capabilities. I think that both package.mask (and package.keywords, etc.) directories are a good idea, and I also think it's a good idea for the package manager to support device nodes, which is particularly useful for the udev and baselayout ebuilds. Funtoo Linux has separate versions of these packages, and these ebuilds are easier to maintain if device nodes are correctly supported by the package manger, and the package.mask directory is a great help to us as well.

We could maintain a patched version of Paludis that would be useable with the Funtoo Portage tree, but I don't want to get into the business of supporting a non-standard package manager as the upstream project seems not seem very supportive of getting these compatibility issues resolved, and thus this could turn into a maintenance burden for Funtoo. So I'd rather just not support Paludis for now.

What about pkgcore?

Pkgcore is not currently compatible with Funtoo Linux but efforts are under way to resolve this.

How do I report a bug?

The best way to report your bug is to describe the issue you are having on the funtoo-dev mailing list. Another option is to ask for support in the #funtoo. In general, it's best to contact us first about an issue you are having, rather than opening a Gentoo bug report, unless you are quite familiar with the issue and are fairly certain that it is not a Funtoo Linux issue.

If you report a bug to Gentoo that may impact Funtoo Linux in some way, please post information about it to the funtoo-dev mailing list so we are aware of the issue.

How do I become a Funtoo developer?

Funtoo is a personal project of mine, so I'm the only real developer. However, I involve everyone on the funtoo-dev mailing list and #funtoo in what I am doing so that patches, feedback, requests, etc. can be shared. My advice is to get involved in the Funtoo community on the mailing list and irc channel.

General Funtoo Stuff

What is funtoo.org?

Funtoo.org is the online home of Daniel Robbins (me) and is a place to put all my stuff.

What kind of stuff?

Well, I have Funtoo Linux, which is a Gentoo Linux variant. Then I have technical articles -- some new, and some updated versions of originals that appeared on IBM developerWorks.

Then I have Metro, an operating system build tool, and I have Keychain, which is a tool to help you manage RSA and DSA keys for ssh.

So Funtoo is not just Funtoo Linux.

What is 'Funtoo' all about? And 'Funtoo Linux'?

Funtoo by itself refers to this site, or the larger Funtoo project run by Daniel Robbins. That's just a fancy way of saying that Funtoo refers to all the stuff I'm doing.

Funtoo Linux refers specifically to my variant of Gentoo Linux.

If you see me use the phrase Funtoo Portage tree or Funtoo ebuild, I'm just talking about our separate (and slightly different) Portage tree, or our version of an ebuild.

What is 'tnufoo'?

tnufoo is funtoo rotated 180 degrees vertically.

How many developers are working on Funtoo Linux?

Funtoo Linux development is led by Daniel Robbins, along with a Core Team that also makes significant contributions to Funtoo Linux development and Funtoo infrastructure.

Is Funtoo Linux a fork of Gentoo Linux?

It depends on your definition of fork. Officially, I am calling Funtoo Linux a Gentoo Linux variant, meaning that it is more like another flavor of Gentoo than a fork.

We share our changes and bug fixes with the Gentoo project, so Gentoo is free to merge in any of our changes at any time. We also merge in Gentoo's changes every 12 hours.

I could officially call Funtoo Linux a fork of Gentoo Linux, but Gentoo could merge most of our changes into Gentoo proper and then what would Funtoo Linux be? It'd be my variant of Gentoo, that's what it'd be. So let's just call it a variant of Gentoo.

What is the best way to interact with the Funtoo community?

I recommend joining the funtoo-dev mailing list and, if desired, hanging out in the #funtoo on freenode.

The funtoo-dev mailing list as well as the #funtoo are unmoderated, open discussion forums for both Funtoo Linux users and developers. In addition, these are also the official lists for discussing other Funtoo projects such as Metro and Keychain.

What Architectures does Funtoo Linux support?

While Funtoo Linux can run on any architecture that Gentoo Linux supports, we are only maintaining Funtoo Linux for x86 and amd64 architectures. Adding support for other architectures may require a little bit of unmasking work in our Portage tree -- or not. We're not testing anything but x86 and amd64, so we don't know :)

How should a developer use package.mask?

We currently have four files in the package.mask directory -- gentoo, funtoo, funtoo-cautionary and sunrise. Gentoo is an almost pristine version of the upstream gentoo package.mask. It differs from gentoo only in that we will remove stuff from it that we no longer want in it, but we don't add masks to this file. So if there is a mask in gentoo, you know it came upstream from Gentoo.

funtoo is where we place our masks. funtoo-cautionary is where we place masks that are designed to shield us from upstream unstable version changes to core packages, since we don't want to simply follow Gentoo unstable -- instead, we want to control when gcc and glibc switch to new versions. sunrise contains a bunch of sunrise and other miscellaneous masks from the mpd overlays. It is currently sort of our "junk drawer" that we'll get around to cleaning up at some point.

Do you use the normal Gentoo system profiles?

I've made some minor changes to the Funtoo Linux profiles/ directory, and I'll continue to make improvements as time goes on. The most recent change I made (as of 17 Jul 2009) was to add net-dns/openresolv to the core system profile. Since Funtoo development focuses primarily on the core system, you can expect our system profiles to be somewhat different from Gentoo's. However, from a user perspective, you use them the same way and we have the same profile names that are in Gentoo.

Is Funtoo Linux More Stable Than Gentoo Linux?

That is a hard question to answer directly, as one person's definition of "stable" may be different than another person's, and I do not know how you intend to use Funtoo Linux. So rather than tackle the question head-on, I can give you some additional information that may help you decide:

  • The goal of Funtoo Linux is to allow me to improve the Gentoo core system and tools. That does mean that I will be periodically changing various parts of Gentoo plumbing from time to time. When I do this, I try to be careful and provide notices of upcoming major changes on the mailing list, Atom feed and on the Web site.
  • Both Funtoo Linux and Gentoo Linux have a stable and unstable (~ - called "current" in Funtoo) tree
  • The Funtoo and Gentoo trees are 99% identical. However, there are signficant differences in certain areas, particularly the core system and Perl, Python and Ruby.
  • Funtoo and Gentoo trees do have some significant differences for core packages, particularly openrc, baselayout, udev and lvm2.
  • If it is important to you, Metro is tested daily to ensure that it can build Funtoo Linux (and Gentoo Linux) successfully. However, these builds are not performed in advance of the changes hitting the public git-based Portage tree.
  • Any Metro Funtoo Linux build failures found are typically fixed in the Funtoo Portage within 0-1 days. Gentoo build failures are only fixed if they are related to an issue with Metro. So there is very fast response in Funtoo to core system build failures. In Gentoo, this process is not as integrated.
  • Funtoo merges in upstream changes from Gentoo Portage every 12 hours.
  • I focus on testing the core, non-GUI/non-X system. Sometimes Funtoo will trail behind in udev revisions that cutting-edge desktop users want to run.
  • Both Funtoo Linux stable and current have OpenRC, dhcpcd-5 and OpenResolv integrated by default.
  • Funtoo Linux current tries to upgrade certain core packages such as udev, gcc and glibc much less frequently and in a more controlled manner than Gentoo unstable. This may or may not be a benefit to you, depending on what you are looking for. Basically, I am trying to offer the package updates of Gentoo Linux unstable without as much of the (too frequent, in my opinion) core system changes that can often cause problems for people.
  • The Funtoo receives Gentoo changes once every 12 hours. In contrast, the Gentoo rsync tree receives updates hourly. This means that the changes in the Funtoo tree are compressed into a single monolithic event, whereas the Gentoo tree undergoes more continual, but less signficant, change every hour.
  • Significant build-related bugs found by Funtoo that also impact Gentoo Linux are sent upstream to bugs.gentoo.org.

Do you use Gentoo's Guide XML for Documentation?

I originally created Gentoo's Guide XML format (which I originally created for Gentoo) for documentation, and started to transition away from it in favor of ReStructuredText. However, now I am trying to support Guide XML and ReStructuredText as they are both useful for different types of things.

Many funtoo.org articles and documents are maintained in ReStructuredText format. HTML versions of the ReStructuredText documentation are generated by first converting the .rst file to XML using rst2xml.py (part of the docutils distribution), and then using XSLT to convert the resultant XML to HTML.

To view the plaintext ReStructuredText version of a document, append /index.rst to any funtoo.org URL. For example, here is the ReStructuredText version of this document

Are you looking for translators?

Many kind people have provided translations of the funtoo.org pages, and the old version of the site used to contain these translations. However, after much consideration, I've decided to not provide translated versions of funtoo.org pages, for several reasons:

  • Translated documents tend to become out-of-date
  • Updating the translated documents is quite a bit of work
  • Most people online seem to have at least a basic grasp of English

For these reasons, I'm going to focus on improving the quantity and quality of English documentation, and not focus on translations for now.

Forking the Portage Tree

I want to fork the Portage tree. How do I do this?

The old way used to involve forking our huge, complete Portage tree. Currently, the best way to do it involves forking the funtoo-overlay, which is much smaller, or creating your own overlay. I have scripts that combine the Funtoo overlay and the Gentoo tree to create a unified Portage tree.

I have forked my own Portage tree. How do I generate metadata for it?

You should only do this if you are creating a unified Portage tree for distribution to users. Otherwise, it is much more efficient to use an overlay for this purpose.

First, add FEATURES="metadata-transfer" to your /etc/make.conf file. Then type the following commands:

# cd /usr/portage
# egencache --update --jobs=4
# cd metadata/cache
# git add .
# git commit -a

egencache is part of sys-apps/portage and was kindly integrated by Zack Medico, Portage maintainer.

Where can I learn more about git?

So, you want to learn more about git, do you? A collection of excellent git resources is now available on the Git Guide.