Difference between pages "ZFS Install Guide" and "Keychain"

(Difference between pages)
(don't forget to install kernel modules)
 
 
Line 1: Line 1:
== Introduction ==
+
{{Article
 +
|Subtitle=Official Project Page
 +
|Summary=Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. Download and learn how to use Keychain on your Linux, Unix or MacOS system.
 +
|Keywords=keychain,ssh,rsa,dsa,gpg,linux,gentoo,macos,download,source code
 +
|Author=Drobbins
 +
}}
 +
<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.
  
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.
+
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 "hook in" to a long-running <tt>ssh-agent</tt> process, allowing your scripts to take advantage of key-based logins.
  
=== Introduction to ZFS ===
+
Those who are new to OpenSSH and the use of public/private keys for authentication may want to check out the following articles by Daniel Robbins, which will provide a gentle introduction to the concepts used by Keychain:
 +
* [[OpenSSH Key Management, Part_1]]
 +
* [[OpenSSH Key Management, Part_2]]
 +
* [[OpenSSH Key Management, Part_3]]
  
Since ZFS is a new technology for Linux, it can be helpful to understand some of its benefits, particularly in comparison to BTRFS, another popular next-generation Linux filesystem:
+
== Download and Resources ==
  
* On Linux, the ZFS code can be updated independently of the kernel to obtain the latest fixes. btrfs is exclusive to Linux and you need to build the latest kernel sources to get the latest fixes.
+
The latest release of keychain is version <tt>2.7.2_beta1</tt>, and was released on July 7, 2014. The current version of keychain supports <tt>gpg-agent</tt> as well as <tt>ssh-agent</tt>.
  
* ZFS is supported on multiple platforms. The platforms with the best support are Solaris, FreeBSD and Linux. Other platforms with varying degrees of support are NetBSD, Mac OS X and Windows. btrfs is exclusive to Linux.
+
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>.
  
* ZFS has the Adaptive Replacement Cache replacement algorithm while btrfs uses the Linux kernel's Last Recently Used replacement algorithm. The former often has an overwhelmingly superior hit rate, which means fewer disk accesses.
+
=== Download ===
  
* ZFS has the ZFS Intent Log and SLOG devices, which accelerates small synchronous write performance.
+
* ''Release Archive''
 +
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.2_beta1.tar.bz2 keychain 2.7.2_beta1]
 +
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.1.tar.bz2 keychain 2.7.1]
  
* ZFS handles internal fragmentation gracefully, such that you can fill it until 100%. Internal fragmentation in btrfs can make btrfs think it is full at 10%. Btrfs has no automatic rebalancing code, so it requires a manual rebalance to correct it.
+
* ''Apple MacOS X Packages''
 +
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.1-macosx.tar.gz keychain 2.7.1 MacOS X package]
  
* ZFS has raidz, which is like RAID 5/6 (or a hypothetical RAID 7 that supports 3 parity disks), except it does not suffer from the RAID write hole issue thanks to its use of CoW and a variable stripe size. btrfs gained integrated RAID 5/6 functionality in Linux 3.9. However, its implementation uses a stripe cache that can only partially mitigate the effect of the RAID write hole.
+
Keychain development sources can be found in the [http://www.github.com/funtoo/keychain keychain git repository]. Please use the [https://bugs.funtoo.org Funtoo Linux bug tracker] and [irc://irc.freenode.net/funtoo #funtoo irc channel] for keychain support questions as well as bug reports.
  
* ZFS send/receive implementation supports incremental update when doing backups. btrfs' send/receive implementation requires sending the entire snapshot.
+
=== Project History ===
  
* ZFS supports data deduplication, which is a memory hog and only works well for specialized workloads. btrfs has no equivalent.
+
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.
  
* ZFS datasets have a hierarchical namespace while btrfs subvolumes have a flat namespace.
+
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.
  
* ZFS has the ability to create virtual block devices called zvols in its namespace. btrfs has no equivalent and must rely on the loop device for this functionality, which is cumbersome.
+
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.
  
The only area where btrfs is ahead of ZFS is in the area of small file
+
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.
efficiency. btrfs supports a feature called block suballocation, which
+
enables it to store small files far more efficiently than ZFS. It is
+
possible to use another filesystem (e.g. reiserfs) on top of a ZFS zvol
+
to obtain similar benefits (with arguably better data integrity) when
+
dealing with many small files (e.g. the portage tree).
+
  
=== Disclaimers ===
+
== Quick Setup ==
  
{{fancywarning|This guide is a work in progress. Expect some quirks.}}
+
=== Linux ===
{{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'''!}}
+
 
+
== Video Tutorial ==
+
 
+
As a companion to the install instructions below, a YouTube video ZFS install tutorial is now available:
+
 
+
{{#widget:YouTube|id=kxEdSXwU0ZI|width=640|height=360}}
+
 
+
== Downloading the ISO (With ZFS) ==
+
In order for us to install Funtoo on ZFS, you will need an environment that provides the ZFS tools. Therefore we will download a customized version of System Rescue CD with ZFS already included. When booting, use the "alternate"-kernel. The ZFS-module won't work with the default kernel.
+
 
+
<pre>
+
Name: sysresccd-3.8.1_zfs_0.6.2.iso  (510 MB)
+
Release Date: 2013-11-03
+
md5sum aa33ef61c5d85ad564372327940498c3
+
</pre>
+
 
+
 
+
'''[http://ftp.osuosl.org/pub/funtoo/distfiles/sysresccd/ Download System Rescue CD with ZFS]'''<br />
+
 
+
== Creating a bootable USB from ISO ==
+
After you download the iso, you can do the following steps to create a bootable USB:
+
  
 +
To install under Gentoo or Funtoo Linux, type
 
<console>
 
<console>
Make a temporary directory
+
###i## emerge keychain
# ##i##mkdir /tmp/loop
+
 
+
Mount the iso
+
# ##i##mount -o ro,loop /root/sysresccd-3.7.1_zfs_0.6.2.iso /tmp/loop
+
 
+
Run the usb installer
+
# ##i##/tmp/loop/usb_inst.sh
+
 
</console>
 
</console>
  
That should be all you need to do to get your flash drive working.
+
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>:
  
When you are booting into system rescue cd, make sure you select the '''alternative 64 bit kernel'''. ZFS support was specifically added to the alternative 64 bit kernel rather than the standard 64 bit kernel.
+
{{file|name=~/.bash_profile|body=
 +
eval `keychain --eval --agents ssh id_rsa`
 +
}}
  
== Creating partitions ==
+
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.
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.
+
  
We will be showing you how to partition it '''manually''' because if you partition it manually you get to create your own layout, you get to have your own separate /boot partition (Which is nice since not every bootloader supports booting from ZFS pools), and you get to boot into RAID10, RAID5 (RAIDZ) pools and any other layouts due to you having a separate /boot partition.
+
=== Apple MacOS X ===
  
==== gdisk (GPT Style) ====
+
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>:
  
'''A Fresh Start''':
+
{{file|name=~/.bash_profile|body=
 +
eval `keychain --eval --agents ssh --inherit any id_dsa`
 +
}}
  
First lets make sure that the disk is completely wiped from any previous disk labels and partitions.
+
{{Fancynote|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.}}
We will also assume that <tt>/dev/sda</tt> is the target drive.<br />
+
  
<console>
+
== Background ==
# ##i##gdisk /dev/sda
+
  
Command: ##i##x ↵
+
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.
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.}}
+
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.
  
Now that we have a clean drive, we will create the new layout.
+
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.
  
'''Create Partition 1''' (boot):
+
== Generating a Key Pair ==
<console>
+
Command: ##i##n ↵
+
Partition Number: ##i##↵
+
First sector: ##i##↵
+
Last sector: ##i##+250M ↵
+
Hex Code: ##i##↵
+
</console>
+
  
'''Create Partition 2''' (BIOS Boot Partition):
+
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:
<console>Command: ##i##n ↵
+
Partition Number: ##i##↵
+
First sector: ##i##↵
+
Last sector: ##i##+32M ↵
+
Hex Code: ##i##EF02 ↵
+
</console>
+
  
'''Create Partition 3''' (ZFS):
+
<console># ##i##ssh-keygen -t dsa
<console>Command: ##i##n ↵
+
Generating public/private dsa key pair.</console>
Partition Number: ##i##
+
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:
First sector: ##i##↵
+
Last sector: ##i##↵
+
Hex Code: ##i##bf00 ↵
+
  
Command: ##i##p ↵
+
<console>Enter file in which to save the key (/root/.ssh/id_dsa): </console>
 +
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.
  
Number  Start (sector)    End (sector)  Size      Code  Name
+
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.''
  1            2048          514047  250.0 MiB  8300  Linux filesystem
+
  2          514048          579583  32.0 MiB    EF02  BIOS boot partition
+
  3          579584      1953525134  931.2 GiB  BF00  Solaris root
+
  
Command: ##i##w ↵
+
Below, I have supplied a passphrase so that my private key file will be encrypted on disk:
</console>
+
  
 +
<console>Enter passphrase (empty for no passphrase): ##i#########
 +
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>
  
=== Format your boot volume ===
+
== Setting up Authentication ==
Format your separate /boot partition:
+
<console># ##i##mkfs.ext2 /dev/sda1</console>
+
  
=== Encryption (Optional) ===
+
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.
If you want encryption, then create your encrypted vault(s) now by doing the following:
+
  
<console>
+
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.
# ##i##cryptsetup luksFormat /dev/sda3
+
# ##i##cryptsetup luksOpen /dev/sda3 vault_1
+
</console>
+
  
=== Create the zpool ===
+
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> :
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/sda3</console>
+
  
{{fancyimportant|If you are using encrypted root, change '''/dev/sda3 to /dev/mapper/vault_1'''.}}
+
{{file|name=~/.bash_profile|body=
 +
eval `keychain --eval id_dsa`
 +
}}
  
{{fancynote|'''ashift<nowiki>=</nowiki>12''' should be use if you have a newer, advanced format disk that has a sector size of 4096 bytes. If you have an older disk with 512 byte sectors, you should use '''ashift<nowiki>=</nowiki>9''' or don't add the option for auto detection}}
+
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:
  
{{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>'''}}
+
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:
  
=== Create the zfs datasets ===
+
This means that you can now <tt>ssh</tt> to your heart's content, without supplying a passphrase.
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>
+
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:
Create some empty containers for organization purposes, and make the dataset that will hold /
+
# ##i##zfs create rpool/ROOT
+
# ##i##zfs create -o mountpoint=/ rpool/ROOT/funtoo
+
  
Optional, but recommended datasets: /home
+
{{file|name=example-script.sh|body=
# ##i##zfs create -o mountpoint=/home rpool/HOME
+
eval `keychain --noask --eval id_dsa` || exit 1
 +
}}
  
Optional, portage tree, distfiles, and binary packages:
+
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>.
# ##i##zfs create rpool/FUNTOO
+
# ##i##zfs create -o mountpoint=/usr/portage -o compression=off rpool/FUNTOO/portage
+
# ##i##zfs create -o mountpoint=/usr/portage/distfiles rpool/FUNTOO/portage/distfiles
+
# ##i##zfs create -o mountpoint=/usr/portage/packages rpool/FUNTOO/portage/packages
+
  
Optional datasets: /usr/src
+
== Keychain Options ==
# ##i##zfs create -o mountpoint=/usr/src rpool/FUNTOO/src
+
</console>
+
  
=== Create your swap zvol ===
+
=== Specifying Agents ===
'''Make your swap +1G greater than your RAM. An 8G machine would have 9G of SWAP (This is kinda big though). For machines with this much memory, You could just make it 2G if you don't have any problems.'''
+
<console>
+
# ##i##zfs create -o sync=always -o primarycache=metadata -o secondarycache=none -o volblocksize=4K -V 1G rpool/swap
+
</console>
+
  
=== Format your swap zvol ===
+
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:
<console>
+
# ##i##mkswap -f /dev/zvol/rpool/swap
+
# ##i##swapon /dev/zvol/rpool/swap
+
</console>
+
  
 +
{{file|name=~/.bash_profile|body=
 +
eval `keychain --agents ssh --eval id_dsa` || exit 1
 +
}}
  
=== Last minute checks and touches ===
+
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.
Check to make sure everything appears fine. Your output may differ depending on the choices you made above:
+
<console>
+
# ##i##zpool status
+
  pool: rpool
+
state: ONLINE
+
  scan: none requested
+
config:
+
  
        NAME        STATE    READ WRITE CKSUM
+
=== Clearing Keys ===
        rpool      ONLINE      0    0    0
+
          sda2      ONLINE      0    0    0
+
  
errors: No known data errors
+
Sometimes, it might be necessary to flush all cached keys in memory. To do this, type:
  
# ##i##zfs list
+
<console># ##i##keychain --clear</console>
rpool              3.10G  15.5G  136K  none
+
Any agent(s) will continue to run.
rpool/HOME          136K  15.5G  136K  /mnt/funtoo/home
+
rpool/ROOT          308K  15.5G  136K  none
+
rpool/ROOT/funtoo  172K  15.5G  172K  /mnt/funtoo
+
rpool/swap        3.09G  18.6G    76K  -
+
</console>
+
  
Now we will continue to install funtoo.
+
=== Improving Security ===
  
== Installing Funtoo ==
+
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.
[[Funtoo_Linux_Installation|Download and extract the Funtoo stage3 and continue installation as normal.]]
+
  
Then once you've extracted the stage3, chroot into your new funtoo environment:
+
=== Stopping Agents ===
<console>
+
Go into the directory that you will chroot into
+
# ##i##cd /mnt/funtoo
+
  
Mount your boot drive
+
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:
# ##i##mount /dev/sda1 /mnt/funtoo/boot
+
  
Bind the kernel related directories
+
<console># ##i##keychain -k all</console>
# ##i##mount -t proc none /mnt/funtoo/proc
+
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:
# ##i##mount --rbind /dev /mnt/funtoo/dev
+
# ##i##mount --rbind /sys /mnt/funtoo/sys
+
  
Copy network settings
+
<console># ##i##keychain -k mine</console>
# ##i##cp /etc/resolv.conf /mnt/funtoo/etc/
+
  
chroot into your new funtoo environment
+
=== GPG ===
# ##i##env -i HOME=/root TERM=$TERM chroot /mnt/funtoo /bin/bash --login
+
 
+
Place your mountpoints into your /etc/mtab file
+
# ##i##cat /proc/mounts > /etc/mtab
+
 
+
Sync your tree
+
# ##i##emerge --sync
+
</console>
+
 
+
=== Add filesystems to /etc/fstab ===
+
 
+
Before we continue to compile and or install our kernel in the next step, we will edit the /etc/fstab file because if we decide to install our kernel through portage, portage will need to know where is your /boot so that it can place the files in there. We also need to update /etc/mtab so our system knows what is mounted
+
  
 +
Keychain can ask you for your GPG passphrase if you provide it the GPG key ID. To find it out:
 
<console>
 
<console>
# ##i##nano /etc/fstab
+
$##i## gpg -k
 
+
pub  2048R/DEADBEEF 2012-08-16
# <fs>                 <mountpoint>    <type>          <opts>          <dump/pass>
+
uid                 Name (Comment) <email@host.tld>
# Do not add the /boot line below if you are using whole-disk zfs
+
sub  2048R/86D2FAC6 2012-08-16
/dev/sda1              /boot          ext2            defaults        0 2
+
/dev/zvol/rpool/swap    none            swap            sw              0 0
+
 
</console>
 
</console>
  
== Kernel Configuration ==
+
Note the '''DEADBEEF''' above is the ID. Then, in your login script, do your usual
To speed up this step, you can install "bliss-kernel" since it's already properly configured for ZFS and a lot of other configurations. The kernel is also compiled and ready to go. To install 'bliss-kernel' type the following:
+
  
 
<console>
 
<console>
# ##i##emerge bliss-kernel
+
$##i## keychain --dir ~/.ssh/.keychain ~/.ssh/id_rsa DEADBEEF
 +
$##i## source ~/.ssh/.keychain/$HOST-sh
 +
$##i## source ~/.ssh/.keychain/$HOST-sh-gpg
 
</console>
 
</console>
  
Now make sure that your /usr/src/linux symlink is pointing to this kernel by typing the following:
+
=== Learning More ===
  
<console>
+
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.
# ##i##eselect kernel list
+
Available kernel symlink targets:
+
[1]  linux-3.10.10-FB.01 *
+
</console>
+
  
You should see a star next to the bliss-kernel version you installed. In this case it was 3.10.10-FB.01. If it's not set, you can type '''eselect kernel set #'''.
+
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.
  
== Installing the ZFS userspace tools and kernel modules ==
+
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 :)
  
<console># ##i##emerge -av zfs spl zfs-kmod</console>
+
* [http://www.ibm.com/developerworks/library/l-keyc.html Common Threads: OpenSSH key management, Part 1] - Understanding RSA/DSA Authentication
 +
* [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
  
(spl = Solaris Porting Layer)
+
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.
 
+
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 ===
+
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:
+
 
+
<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.
+
 
+
=== LILO ===
+
Before you do this, make sure the following checklist is followed:
+
* /dev/, /proc and /sys are mounted.
+
* Installed the sys-fs/zfs package from the tree.
+
Once the above requirements are met, LILO can be installed.
+
 
+
Now we will install LILO.
+
<console># ##i##emerge -av sys-boot/lilo</console>
+
Once the installation of LILO is complete we will need to edit the lilo.conf file.
+
<console># ##i##nano /etc/lilo.conf
+
boot=/dev/sda
+
prompt
+
timeout=4
+
default=Funtoo
+
 
+
image=/boot/bzImage
+
      label=Funtoo
+
      read-only
+
      append="root=rpool/ROOT/funtoo"
+
      initrd=/boot/initramfs
+
</console>
+
All that is left now is to install the bootcode to the MBR.
+
 
+
This can be accomplished by running:
+
<console># ##i##/sbin/lilo</console>
+
If it is successful you should see:
+
<console>
+
Warning: LBA32 addressing assumed
+
Added Funtoo + *
+
One warning was issued
+
</console>
+
 
+
== 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
+
# You only need to add --luks if you used encryption
+
# ##i##genkernel --zfs --luks initramfs
+
</console>
+
 
+
=== Bliss Initramfs Creator ===
+
If you are encrypting your drives, then add the "luks" use flag to your package.use before emerging:
+
 
+
<console>
+
# ##i##echo "sys-kernel/bliss-initramfs luks" >> /etc/portage/package.use
+
</console>
+
 
+
Now install the creator:
+
 
+
<console>
+
# ##i##emerge bliss-initramfs
+
</console>
+
 
+
 
+
Then go into the install directory, run the script as root, and place it into /boot:
+
<console># ##i##cd /opt/bliss-initramfs
+
# ##i##./createInit
+
# ##i##mv initrd-<kernel_name> /boot
+
</console>
+
'''<kernel_name>''' is the name of what you selected in the initramfs creator, and the name of the outputted file.
+
 
+
== Using boot-update ==
+
=== /boot on separate partition ===
+
If you created a separate non-zfs partition for boot then configuring boot-update is almost exactly the same as a normal install except that auto detection for root does not work. You must tell boot-update what your root is.
+
==== Genkernel ====
+
If your using genkernel you must add 'real_root=ZFS=<root>' and 'dozfs' to your params.
+
Example entry for boot.conf:
+
<console>
+
"Funtoo ZFS" {
+
        kernel vmlinuz[-v]
+
        initrd initramfs-genkernel-x86_64[-v]
+
        params real_root=ZFS=rpool/ROOT/funtoo
+
        params += dozfs
+
        # Also add 'params += crypt_root=/dev/sda2' if you used encryption
+
        # Adjust the above setting to your system if needed
+
}
+
</console>
+
 
+
==== Bliss Initramfs Creator ====
+
If you used the Bliss Initramfs Creator then all you need to do is add 'root=<root>' to your params.
+
Example entry for boot.conf:
+
<console>
+
"Funtoo ZFS" {
+
        kernel vmlinuz[-v]
+
        initrd initrd[-v]
+
        params root=rpool/ROOT/funtoo quiet
+
        # If you have an encrypted device with a regular passphrase,
+
        # you can add the following line
+
        params += enc_root=/dev/sda3 enc_type=pass
+
}
+
</console>
+
 
+
After editing /etc/boot.conf, you just need to run boot-update to update grub.cfg
+
<console># ##i##boot-update</console>
+
 
+
=== /boot on ZFS ===
+
TBC - pending update to boot-update to support this
+
 
+
== Final configuration ==
+
=== Add the zfs tools to openrc ===
+
<console># ##i##rc-update add zfs boot</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 tarball that you downloaded earlier so it doesn't take up space.
+
# ##i##cd /
+
# ##i##rm stage3-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##umount -l proc dev sys boot
+
 
+
Turn off the swap
+
# ##i##swapoff /dev/zvol/rpool/swap
+
 
+
Export the zpool
+
# ##i##cd /
+
# ##i##zpool export 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.
+
 
+
== After reboot ==
+
=== Create initial ZFS Snapshot ===
+
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 system, type the following:
+
<console># ##i##zfs snapshot -r rpool@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 (This will only revert your / dataset while keeping the rest of your data intact):
+
<console># ##i##zfs rollback rpool/ROOT/funtoo@install</console>
+
 
+
{{fancyimportant|'''For a detailed overview, presentation of ZFS' capabilities, as well as usage examples, please refer to the [[ZFS_Fun|ZFS Fun]] page.'''}}
+
  
 
[[Category:HOWTO]]
 
[[Category:HOWTO]]
[[Category:Filesystems]]
+
[[Category:Projects]]
[[Category:Featured]]
+
[[Category:First Steps]]
 
+
[[Category:Articles]]
__NOTITLE__
+
{{ArticleFooter}}

Revision as of 16:22, January 5, 2015

Official Project Page

Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. Download and learn how to use Keychain on your Linux, Unix or MacOS system.

Support Funtoo and help us grow! Donate $15 per month and get a free SSD-based Funtoo Virtual Container.

Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. It acts as a frontend to ssh-agent and ssh-add, but allows you to easily have one long running ssh-agent process per system, rather than the norm of one ssh-agent per login session.

This dramatically reduces the number of times you need to enter your passphrase. With keychain, you only need to enter a passphrase once every time your local machine is rebooted. Keychain also makes it easy for remote cron jobs to securely "hook in" to a long-running ssh-agent process, allowing your scripts to take advantage of key-based logins.

Those who are new to OpenSSH and the use of public/private keys for authentication may want to check out the following articles by Daniel Robbins, which will provide a gentle introduction to the concepts used by Keychain:

Download and Resources

The latest release of keychain is version 2.7.2_beta1, and was released on July 7, 2014. The current version of keychain supports gpg-agent as well as ssh-agent.

Keychain is compatible with many operating systems, including AIX, *BSD, Cygwin, MacOS X, Linux, HP/UX, Tru64 UNIX, IRIX, Solaris and GNU Hurd.

Download

Keychain development sources can be found in the keychain git repository. Please use the Funtoo Linux bug tracker and #funtoo irc channel for keychain support questions as well as bug reports.

Project History

Daniel Robbins originally wrote keychain 1.0 through 2.0.3. 1.0 was written around June 2001, and 2.0.3 was released in late August, 2002.

After 2.0.3, keychain was maintained by various Gentoo developers, including Seth Chandler, Mike Frysinger and Robin H. Johnson, through July 3, 2003.

On April 21, 2004, Aron Griffis committed a major rewrite of keychain which was released as 2.2.0. Aron continued to actively maintain and improve keychain through October 2006 and the keychain 2.6.8 release. He also made a few commits after that date, up through mid-July, 2007. At this point, keychain had reached a point of maturity.

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 bugs.gentoo.org. Daniel continues to maintain keychain and supporting documentation on funtoo.org, and plans to make regular maintenance releases of keychain as needed.

Quick Setup

Linux

To install under Gentoo or Funtoo Linux, type

# emerge keychain

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 id_dsa and id_dsa.pub in your ~/.ssh/ directory. Add the following to your ~/.bash_profile:

~/.bash_profile
eval `keychain --eval --agents ssh id_rsa`

If you want to take advantage of GPG functionality, ensure that GNU Privacy Guard is installed and omit the --agents ssh option above.

Apple MacOS X

To install under MacOS X, install the MacOS X package for keychain. Assuming you have an id_dsa and id_dsa.pub key pair in your ~/.ssh/ directory, add the following to your ~/.bash_profile:

~/.bash_profile
eval `keychain --eval --agents ssh --inherit any id_dsa`
Note

The --inherit any 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

You're probably familiar with ssh, which has become a secure replacement for the venerable telnet and rsh commands.

Typically, when one uses ssh to connect to a remote system, one supplies a secret passphrase to ssh, which is then passed in encrypted form over the network to the remote server. This passphrase is used by the remote sshd server to determine if you should be granted access to the system.

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. keychain has been designed to make it easy to take advantage of the benefits of RSA and DSA authentication.

Generating a Key Pair

To use RSA and DSA authentication, first you use a program called ssh-keygen (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. ssh-keygen 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:

# ssh-keygen -t dsa
Generating public/private dsa key pair.

You would then be prompted for a location to store your key pair. If you do not have one currently stored in ~/.ssh, it is fine to accept the default location:

Enter file in which to save the key (/root/.ssh/id_dsa): 

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.

Below, I have supplied a passphrase so that my private key file will be encrypted on disk:

Enter passphrase (empty for no passphrase): #######
Enter same passphrase again: #######
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 .+*.|
+-----------------+

Setting up Authentication

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 ~.ssh/authorized_keys file, if such a file exists. If it doesn't exist, you can simply create a new authorized_keys file in the remote account's ~/.ssh directory that contains the contents of your local id_dsa.pub file.

Then, if you weren't going to use keychain, you'd perform the following steps. On your local client, you would start a program called ssh-agent, which runs in the background. Then you would use a program called ssh-add to tell ssh-agent about your secret private key. Then, if you've set up your environment properly, the next time you run ssh, it will find ssh-agent running, grab the private key that you added to ssh-agent using ssh-add, and use this key to authenticate with the remote server.

Again, the steps in the previous paragraph is what you'd do if keychain wasn't around to help. If you are using keychain, and I hope you are, you would simply add the following line to your ~/.bash_profile or if a regular user to~/.bashrc :

~/.bash_profile
eval `keychain --eval id_dsa`

The next time you log in or source your ~/.bash_profile or if you use ~/.bashrc, keychain will start, start ssh-agent for you if it has not yet been started, use ssh-add to add your id_dsa private key file to ssh-agent, and set up your shell environment so that ssh will be able to find ssh-agent. If ssh-agent is already running, keychain will ensure that your id_dsa private key has been added to ssh-agent and then set up your environment so that ssh can find the already-running ssh-agent. It will look something like this:

Note that when keychain 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 keychain -- 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, ssh-agent 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:

This means that you can now ssh to your heart's content, without supplying a passphrase.

You can also execute batch cron jobs and scripts that need to use ssh or scp, 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:

example-script.sh
eval `keychain --noask --eval id_dsa`

The extra --noask option tells keychain 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 ssh-agent.

Keychain Options

Specifying Agents

In the images above, you will note that keychain starts ssh-agent, but also starts gpg-agent. Modern versions of keychain also support caching decrypted GPG keys via use of gpg-agent, and will start gpg-agent by default if it is available on your system. To avoid this behavior and only start ssh-agent, modify your ~/.bash_profile as follows:

~/.bash_profile
eval `keychain --agents ssh --eval id_dsa`

The additional --agents ssh option tells keychain just to manage ssh-agent, and ignore gpg-agent even if it is available.

Clearing Keys

Sometimes, it might be necessary to flush all cached keys in memory. To do this, type:

# keychain --clear

Any agent(s) will continue to run.

Improving Security

To improve the security of keychain, some people add the --clear option to their ~/.bash_profile keychain 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.

Stopping Agents

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:

# keychain -k all

If you have other agents running under your user account, you can also tell keychain to just stop only the agents that keychain started:

# keychain -k mine

GPG

Keychain can ask you for your GPG passphrase if you provide it the GPG key ID. To find it out:

$ gpg -k
pub   2048R/DEADBEEF 2012-08-16
uid                  Name (Comment) <email@host.tld>
sub   2048R/86D2FAC6 2012-08-16

Note the DEADBEEF above is the ID. Then, in your login script, do your usual

$ keychain --dir ~/.ssh/.keychain ~/.ssh/id_rsa DEADBEEF
$ source ~/.ssh/.keychain/$HOST-sh
$ source ~/.ssh/.keychain/$HOST-sh-gpg

Learning More

The instructions above will work on any system that uses bash as its default shell, such as most Linux systems and Mac OS X.

To learn more about the many things that keychain can do, including alternate shell support, consult the keychain man page, or type keychain --help | less for a full list of command options.

I also recommend you read my original series of articles about OpenSSH that I wrote for IBM developerWorks, called OpenSSH Key Management. Please note that keychain 1.0 was released along with Part 2 of this article, which was written in 2001. keychain has changed quite a bit since then. In other words, read these articles for the conceptual and OpenSSH information, but consult the keychain man page for command-line options and usage instructions :)

As mentioned at the top of the page, keychain development sources can be found in the keychain git repository. Please use the funtoo-dev mailing list and #funtoo irc channel for keychain support questions as well as bug reports.


Support Funtoo and help us grow! Donate $15 per month and get a free SSD-based Funtoo Virtual Container.

Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. Download and learn how to use Keychain on your Linux, Unix or MacOS system.
About the Author

Daniel Robbins is best known as the creator of Gentoo Linux and author of many IBM developerWorks articles about Linux. Daniel currently serves as Benevolent Dictator for Life (BDFL) of Funtoo Linux. Funtoo Linux is a Gentoo-based distribution and continuation of Daniel's original Gentoo vision.

Got Funtoo?

Have you installed Funtoo Linux yet? Discover the power of a from-source meta-distribution optimized for your hardware! See our installation instructions and browse our CPU-optimized builds.

Funtoo News

Drobbins

ARM Rebuild

ARM systems will use new stage3's that are not compatible with earlier versions.
2015-06-27 by Drobbins
Drobbins

ABI X86 64 and 32

Funtoo Linux has new 32-bit compatibility libraries inherited from Gentoo. Learn about them here.
2015-06-18 by Drobbins
Drobbins

Pre-built kernels!

Funtoo stage3's are now starting to offer pre-built kernels for ease of install. read more....
2015-05-12 by Drobbins
More...

More Articles

Browse all our Linux-related articles, below:

A

B

F

G

K

L

M

O

P

S

T

W

X