Horrell.ca

A Ghost blog (not a blog about ghosts).

Creating a Custom FreeBSD 10 ISO with Automated Installation

Last month I was working on a FreeBSD 10.1 KVM image for SmartOS, SmartDataCenter and the Joyent Public Cloud. The fisrt version of the image was released a few weeks ago and I'd like to share how I went about building the image. More specifically, I'd like to provide an overview of how I built a custom FreeBSD 10.1 ISO that I use as part of my build process.

A Little Backgound

If you're not familiar with how KVM images are created for Smartos/SmartDataCenter the general workflow goes like this:

  1. Create a blank KVM VM
  2. Boot it with an installation ISO (in this case a FreeBSD ISO)
  3. Install the OS via the ISO
  4. Install the guest tools for the OS and customize the installation
  5. Shut the VM down (poweroff)
  6. Take a ZFS snapshot of the VM
  7. Save the ZFS snapshot as a file using the zfs send command
  8. Finally, create an image manifest for the image

For more detail about all of the steps above, you can read more in the SDC7 doc under How to Create a KVM Image.

For this post, I'm going to focus on steps 3 to 5 which are all handled via a custom ISO I built and helps to speed up the whole process tremendously.

Building a Custom FreeBSD 10.1 ISO

Before I begin, you can find all my scripts and files I used to build a custom FreeBSD ISO on GituHub here: mi-freebsd-10 . Pretty much everything I'm going to talk about can be found in the build_freebsd_iso script, so if you want take a look at that first, got for it.

Building a custom FreeBSD ISO is fairly easy but there are a few catches (more on that later). Once you have the source ISO (e.g., FreeBSD-10.1-RELEASE-amd64-disc1.iso) you mount it, make the modififications you need, then create a new custom ISO. If you're doing this under FreeBSD, it would look something like this:

# Mount the ISO using /mnt/freebsd-iso as the mount point
mount -t cd9660 /dev/`mdconfig -f FreeBSD-10.1-RELEASE-amd64-disc1.iso` /mnt/freebsd-iso

# Copy the ISO contents to /mnt/custom-freebsd-iso
rsync -aq  /mnt/freebsd-iso/ /mnt/custom-freebsd-iso

# After making modifications to /mnt/custom-freebsd-iso,
# create a new ISO
CUSTOM_ISO_TITLE=$(isoinfo -d -i ${ISO_DIR}/${ISO} | grep "Volume id" | awk '{print $3}')
mkisofs -J -R -no-emul-boot \
-V "$CUSTOM_ISO_TITLE" \
-p "Joyent" -b boot/cdboot \
-o freebsd-10-custom.iso /mnt/custom-freebsd-iso

One thing you'll notice about the above code is that I'm geting the ISO label using isoinfo. Starting with the FreeBSD 10.1 release, each ISO lable (or "Volume ID") is unique and is based on the release information (version, architecture, that kind if thing). If you don't use the correct lable in your custom ISO, the FreeBSD installation will fail spectacularly! I learned this the hard way...

As for actually customizing the ISO itself, there are a couple of tricks to that. First, modifications you make to the ISO won't actually be included in your FreeBSD installation. So for example, if you make changes to /mnt/custom-freebsd-iso/etc/rc.conf it won't be included in the installation when you start the install process. Typically you'd want to do things like add networking info to the rc.conf file so the installer has network access (ifconfig_vtnet0="DHCP") or shorten the boot delay by adding autoboot_delay="5" to /mnt/custom-freebsd-iso/boot/loader.conf (the default is 10 seconds). So what if you want to have an installation that has modifications to the rc.conf file? And how do you add new files to the installation? Well, it turns out that FreeBSD allows you to script the installation process!

Automating the Installation

FreeBSD 9.0 introduced a new installer called bsdinstall. When you boot a FreeBSD 9.0 or newer ISO the installer is automatcially started once the boot timer runs out, which kicks off the bsdinstall process.

You can auomtate the installation by including a file called installerconfig in the /etc/ folder of the ISO. When the FreeBSD installation starts it looks for that file. The file allows you to set some configuration defaults in a "preamble" section using environement variables. It's similar to a Kickstart file you'd use in Fedora or CentOS. If you take a look at the installerconfig file in the mi-freebsd-10 repos you'll see that I have it partition vtbd0 using the typical defaults:

PARTITIONS=vtbd0

You'll also notice I'm telling the installer to include the following distributions:

DISTRIBUTIONS="kernel.txz base.txz joyent.txz"

If you want a minimal FreeBSD install, you'd typically just have kernel.txz base.txz here. So what's the joyent.txz distribution file and where did it come from? Glad you asked! That's how I install the various guest tools I need for our KVM image to run under SmartOS and SmartDataCenter. I'll get back to that in a bit, but there's more stuff in the installerconfig script I want to cover.

After the preamble section theres the "Setup Script" which starts with a shebang:

 #!/bin/sh

Here is where you do all your customization occurs. This section is run after the FreeBSD installation completes. Looking at the installerconfig file on GitHub you can see this is where I do things like modify the rc.conf file for the isntallation, create a custom /etc/motd file and install packages via pkg install -y. But what about adding new files?

Adding a Custom Distribution File

The installerconfig file lets you do a lot of useful things. One thing that you can't do is copy files into the installation. This is because at this point the installation is all happeing within a chroot. By default that's the /mnt direcory (which you can change via the BSDINSTALL_CHROOT environment variable, so the installation is run in that directory with no visability to anything outside of it. That means you can't copy files over using the scripted part of installerconfig. This is where the joyent.txz distribution comes in.

To install files to the installation, you just save them all as a distribution file, the add that file to DISTRIBUTIONS= in the preamble of installerconfig. The bsdinstall process will take you distrubution file and unpack it to where it needs to go.

Here's the basic steps for creating the distrubution file called custom. Let's say you have a custom rc.conf file that you want to include. Creat a directory called custom_files.

mkdir custom_files

The rc.conf file likes in /etc, so you need to create an /custom_files/etc folder to match:

mkdir custom_files/etc

Now, add your file to custom_files/etc and create the distrubution using the tar command:

cp rc.conf custom_files/etc/
cd custom_files
tar -cvJpf ../custom.txz ./etc

And that's it, you're custom rc.conf file is now in a distribution file called "custom.txz". If you include in in the preamble part of your installerconfig file (e.g., DISTRIBUTIONS="kernel.txz base.txz custom.txz"), bsdinstall will unpack and copy eveything in your custom distribution over to their respective directories.

One final thing to note about the installerconfig: at the end of the file I'm issuing the poweroff command. Normally the bsdisntall process will run what's after the shebang and then auomatically reboot. Since I'm creating a SmartOS/SmartDataCenter image, I don't want that to happen because I need to do a snapshot. Issueing a full shutdown at the end prevents the automatic reboot from happening.

So that's pretty much it. The above information should hopefully be useful to anyone who wants to create a custom FreeBSD ISO with an aumtomated/unattended installation.

ANd special thanks to Daniel Malon who provide a lot of help and introduced me to the bsdinstall man page :)

Switching over from Textpattern to Ghost

I recently switched Horrell.ca from Textpattern to Ghost. Chances are there are a bunch of broken links to files and such. I'm still tweaking and fixing things and reworking the site design, so expect more changes in the coming months :)

For anyone else who wants to attempt this, a word of warning: there's no easy way to export content from Textpattern to import into Ghost. Ideally, a Textpattern plugin for this would help tremendously, but I wasn't able to find one. I was going to attempt to create one myself, but it's been so long since I've worked in PHP or created a Textpattern plugin that it didn't seem to be worth my time. Instead I (mostly) followed the instructions I found here. The short version of what you have to do: you need to temporarily setup a WordPress blog, import your Textpattern posts into that, then export your posts via a Ghost WordPress plugin, then import into Ghost. Yeah. If you use Textpattern and are thinking about moving to Ghost, it might be best to wait for a bit until bettor options come up.

Despite all that, at least for me, the switch has been worthwhile. It's a great platform for writting and since it runs on Node.js, it's very light on resources. I was able to resize my current Joyent SmartOS instance down significantly since removing Apache and MySQL from the equation.

Speaking of SmartOS instances, I created a handy script for getting Ghost up and running on Joyent called smarty-ghost . It works fairly well and takes care of setting up the SMF manifest for you. I'll be improving that script over time and the install process should become much simpler when Ghost becomes an published npm package.

Oh, and while I was moving things around on my site I put all the Textpattern plugins I created over the years on GitHub. I probably won't be using Textpattern much or contributiing to the ecosystem anymore, but my old code is out there for anyone who might find it usefull. Here's a list of links to each plugin repo:

I could watch this all day

Puppy

Installing mod_cloudflare on a Joyent SmartMachine

CloudFlare is a great service and I’ve been using for my horrell.ca site for some time. It speeds everything up, acts as a firewall protecting your site from bots and jerks, and also provides IPv6 support. One side affect of using CloudFlare is the Apache logs for your site will show IP addresses from the CloudFlare network for any site visitors rather than the true visitors IP address. You can fix that by installing the mod_cloudflare Apache module.

Here’s how to install it on a new Joyent SmartMachine

  1. First, download the mod_cloudflare.c source file from CloudFlare’s Github repos (the -L flag makes sure curl follows any redirects):

    curl -OL https://raw.github.com/cloudflare/CloudFlare-Tools/master/mod_cloudflare.c
  2. Install the gcc compiler:

    pkgin install gcc47
  3. Now compile and install the module:

    apxs -c -i mod_cloudflare.c

    If you have a 64 bit machine, you’ll need to use something like this instead:

    apxs -Wc,-m64 -Wl,-m64 -c -i mod_cloudflare.c
  4. Set the permissions:

    chmod 755 /opt/local/lib/httpd/mod_cloudflare.so
  5. Add this to your /opt/local/etc/httpd/includes/dso.conf (this will load the module when Apache starts):

    LoadModule cloudflare_module lib/httpd/mod_cloudflare.so
  6. Now refresh Apache to load the module:

    svcadm refresh apache

And that’s it! If you check your Apache logs (/var/log/httpd/access.log or /home/NAMEOFSITE/logs/access.log) you should start seeing accurate IP addresses.

You can check if the installation went smoothly with:

svcs -vx apache

If Apache is in maintenance, chances are something went wrong with loading the module. The /var/svc/log/network-apache:default.log service log file will give an idea of what you need to fix.

Periodically, CloudFlare adds new IP addresses to their network, so you’ll need to reinstall the module. You don’t need to do anything special for that, just repeat the above steps using the updated mod_cloudflare.c. source file. I follow the git repos for changes (which doesn’t happen that often).

Adding Icons to Folder Names in iOS

The introduction of folders to iOS was a welcome addition to keeping your home screen tidy. Folders allows you to sensible group like applications and then give the folder a given name, like "Games" for all your game apps etc. In iOS 5, Emoji support was added which means you can also use Emoji as icons in your folder names for added bit of flare, like this:

iPHone home screen

Cool huh?

So here's what you need to do to enable Emoji and then use it in a folder name.

First, enable Emoji support by going to SettingsGeneralKeyboardInternational KeyboardsAdd New KeyboardEmoji

All done? Good! Now, touch and hold a folder you want to add an Emoji icon to and then touch it again and you'll see something like this:

Edit folder name screen

Cool, now touch the folder name (in this example Games) and you'll see something like this:

You may have noticed the new globe icon on the keyboard . Touch it and you'll see something like this:

Emoji Keyboard

Tada, an Emoji keyboard!

From here, pick the Emoji you'd like to use, insert it into the folder name (I like to put them at the beginning), touch the globe icon again and then touch Done. The keyboard will then disappear and you can press the Home button to save you changes.

You may have noticed that I had an  icon for the folder in the top right, but that icon is not actually available via the Emoji keyboard. I used Neven Mrgan’s cool Glyphboard (Glyphboard iPhone web app) to add it. From Glyphboard, I just copied the  icon and then pasted it in the folder name.

Installing node and npm on a Joyent SmartMachine

Here are some updated instructions for installing the latest stable version of node (v0.4.12), as well as npm, on a Joyent SmartMachine.

These instructions install node in the ~/local directory avoiding the need for root privileges when installing things with npm, which is bad.

First, create a ~src/ directory — this is where we’ll download the latest version of node.

mkdir ~/src  
cd ~/src  
curl -O http://nodejs.org/dist/node-v0.4.12.tar.gz  

Now untar it:

gtar -xpf node-v0.4.12.tar.  

Create the @~/local@ directory if it doesn’t already exist:

mkdir ~/local  

Now lets add it to your PATH:

echo 'export PATH=$HOME/local/bin:${PATH}' >> ~/.bashrc  
. ~/.bashrc

Now, configure, build, and install node:

cd node-v*  
./configure --with-dtrace --prefix=~/local
gmake install  

The gmake part will probably take the longest. And you’ve probably noticed I’m using gtar instead of tar and gmake instead of make. There are some difference between the Solaris versions and the GNU versions.

Ok, now let’s get things setup for npm:

echo tar = gtar >> ~/.npmrc  
echo root = $HOME"/.node_libraries" >> ~/.npmrc  
echo binroot = $HOME"/local/bin" >> ~/.npmrc  
echo manroot = $HOME"/local/share/man" >> ~/.npmrc  

Ok, now lets install npm:

curl http://npmjs.org/install.sh | sh  

And that’s it!

Disabling the Caps Lock Key on a Mac

I hate the caps lock key. Hate. I'm always, always pressing it by accident. I don't do it that often on my iMac, but boy howdy, I click it all the time on my MacBook Pro. At my old gig, when I did the nine to five thing in a beige cubicle (it might have been a dirty white, actually) I removed it from the keyboard and put it in a drawer (see blurry photo here. Now that's just not something I want to do with my Mac hardware. The IBM keyboard at work was easy enough, but I don't even know if it's possible on the newer Mac keyboards. Plus it looks bad and isn';t the most elegant solution so I've had to put up with it. Until now!

If you own a Mac and have the same stewing hate for the caps lock key that I do, here's how you can disable it.

  1. Open System Preferences
  2. Select Keyboard
  3. Click the Modifier Keys... button. You should now see something like this:
    Modifier Keys preference
  4. Change the Caps Lock key value to No Action so that it looks like this:
    Modifier Keys preference, Caps Lock key disabled
  5. Click OK.

And thats it, no more caps lock key madness!

com.akamai.client.plist errors

So you use a Mac and you notice that you see lots of errors like this in the Console.app application:

10-12-20 2:43:38 PM    com.apple.launchd.peruser.501[242]  (com.akamai.client.plist[8486]) posix_spawn("/Applications/Akamai/loader.pl", ...): No such file or directory  
10-12-20 2:43:38 PM    com.apple.launchd.peruser.501[242]  (com.akamai.client.plist[8486]) Exited with exit code: 1  
10-12-20 2:43:38 PM    com.apple.launchd.peruser.501[242]  (com.akamai.client.plist) Throttling respawn: Will start in 10 seconds  

This happens every ten seconds and you may even notice some performance issues with your Mac because of this. Thanks to this post from Ignored By Dinosaurs, I was able to finally figure out the cause. This error shows up after you've deleted the Akamai download manager that Adobe forces you to use to download one of their products.

I have a different solution to getting rid of this error though, one that does not involve downloading the Akamai download manager again.

First, start the Terminal.app application (located in the /Applications/Utilities folder).

Next, in Terminal.app run this:

launchctl unload ~/Library/LaunchAgents/com.akamai.client.plist  

That will stop the annoying com.akamai.client.plist job and unload it's launchd config.

Now let's remove the com.akamai.client.plist config completely so it doesn't start up again. From Terminal.app, run this:

rm -rf ~/Library/LaunchAgents/com.akamai.client.plist  

Now, log out and back in again. You can verify the com.akamai.client.plist entry is not loaded by running this from Terminal.app:

launchctl list com.akamai.client.plist  

If it produces the launchctl list returned unknown response error, then you know it's gone.

Relief!