====== Updating pkgsrc ======

The [[accelerators:pkgsrc|pkgsrc]] packaging system uses quarterly release scheme, where only the latest release is being maintained in terms of updates and security patches. There is also a //current// branch available over CVS. Accelerators are built using quarterly releases:

  * [[2007Q4]], released Jan 8, 2008, on Accelerators deployed March 20 until Nov 3rd
  * [[2008Q1]], released Apr 13, 2008, we are skipping this version ...
  * [[2008Q2]], released July 26, 2008, adapted for Accelerators deployed Nov 4th (2.1.4)
  * [[2008Q3]], to be released end of September

There are typically major difference between the releases. E.g. with 2008Q1, OpenSSL 0.9.8 was made current, which changes dependencies in most major packages, ultimately resulting in a rebuild of all. It is a good idea to update your Accelerator to the most recent release available, so stay on top of software updates and security patches.

<note important>
The following document shows how to update your Accelerator to the most recent versions of packages built by Joyent. Make sure you visit specific issues related to the release you're updating **to** (e.g. [[2008Q2]]). Also note that we currently assume the most typical situation where Accelerators were built with the 2007Q4 package set. If you updated manually to e.g. 2008Q1, you may need to adjust the following steps (i.e. not just copy/paste).
</note>

===== Getting the tools ready =====

<note warning>
If you have any software built yourself using pkgsrc that was not built by Joyent, and have not made binary packages, following this tutorial will leave you with that software uninstalled and deleted, and you'll need to re-build. If you do have binary packages built, you'll be able to re-add them at the end. It is advisable to update your local pkgsrc tree to that of 2008Q2 of course, to match the new versions installed as per this article.
</note>

This procedure is intended to run as root. First, make sure you switch to 'root' by using your preferred way. Both using 'su -' (providing root's password), or 'sudo -i' (providing your sudo user's password) would work.

<code bash>
/opt/local/bin/sudo -i
</code>

Now change your profile to talk to the new release repository.

<code bash>
/opt/local/bin/gsed -i'' '/PKG_PATH/s/2007Q4/2008Q2/' /root/.profile
</code>

Now raise the PKG_PATH variable in your existing shell too:

<code bash>
export PKG_PATH=http://pkgsrc.joyent.com/2008Q2/All
</code>

If haven't updated to 2008Q2 or newer yet (which means that you're on 2007Q4), grab the updated PKGSRC config file (mk.conf):

<code bash>
mv /opt/local/etc/mk.conf /opt/local/etc/mk.conf.old
/opt/local/bin/curl -o /opt/local/etc/mk.conf http://pkgsrc.joyent.com/2008Q2/mk.conf
</code>

Install the pkg_chk tool (it's patched to work properly, so make sure to get the one from our 2008Q2 repository - should be version 1.95):

<code bash>
/opt/local/sbin/pkg_add -u pkg_chk
</code>

===== Updating =====

Run pkg_chk in 'test' mode to see all the packages that will be updated:

<code bash>
/opt/local/sbin/pkg_chk -ubn
</code>

The test run end with an error messages claiming a //pkg_chk_update.conf// file cannot be accessed, but that's actually OK (since no files are being created in a test run). If you see a stream of packages for which a newer version exists, things are good.

Now, before you actually push the red button, it makes sense to plan. The update typically takes a few minutes, and software may become unavailable during the process, so it's a good measure to think of it as 'server maintenance' or 'downtime' even, and plan accordingly. Can you claim a //maintenance// and shut off all service? Good. If not letting your users/visitors know would work. Just in case.

When you're ready to go on:

<code bash>
/opt/local/sbin/pkg_chk -ubk
</code>

What happens is that pkg_chk first makes a map of all that will be updated. Then it deletes all packages to be processed. And finally re-adds them from the Joyent binary package repository. The '-k' flag makes it continue onto other packages if any package update fails, so feel free to omit 'k' if you want stop immediately when something like that happens. Note however that pkg_chk will be able to resume work any time, and any failed updates will be remembered, until reconciled eventually.

After the first run, inspect the output. You can re-run to get rid of all that succeeded in the first run, and only see the failures.
===== pkgsrc system packages =====

There are some system packages used by pkgsrc itself, that deserve an update (pax, tnftp, pkg_install, bmake and bootstrap-mk-files). A workaround is needed though, because these tools are involved in the very process of updating packages. The Catch XXII. Let's use a temporary location for these to overcome:

<code bash>
mkdir -p /tmp/pkgsrc.safe
cp -p `pkg_info -L tnftp pax pkg_install bmake|grep bin` /tmp/pkgsrc.safe/
cp -p `pkg_info -L bootstrap-mk-files|grep share` /tmp/pkgsrc.safe/
/opt/local/sbin/pkg_delete -ff tnftp pax pkg_install bmake bootstrap-mk-files
ln -s /tmp/pkgsrc.safe/ftp /opt/local/bin/ftp
ln -s /tmp/pkgsrc.safe/pax /opt/local/bin/pax
ln -s /tmp/pkgsrc.safe/tar /opt/local/bin/tar
/tmp/pkgsrc.safe/pkg_add tnftp pkg_install 
/opt/local/sbin/pkg_add pax bmake
</code>

===== Other packages =====

See particular release's page on packages that need special handling:

  * [[2008Q1]]
  * [[2008Q2]]