Blastwave.org End User Guide

This page is a guide for users of blastwave.org packages, to give you an idea of what to expect from our packages, and how best to use them.

Expectations
Announcements
Release Program
Using programs in our packges
Package upgrades
Program documentation
Relocation from /opt/csw
Large scale deployments
Mailing lists
FAQs

Expectations

First of all, you should expect to have a fairly painless experience using any package from blastwave. If any software does not install or setup in a reasonably straightforward manner, file a bug report against the package.
Blastwave packages are targetted at both end-users, and professional deployment. For the most part, they are suitable for deployment both locally, and on an NFS-shared filesystem. Packages usually install their software under /opt/csw

Some packages, however, do not make sense to deploy over NFS. Software that runs as a server demon, usually falls into this category (eg: mysql). It is assumed that servers will have packages installed locally, rather than over NFS. For this reason, server-targetted packages may install some files outside /opt/csw. The usual reason for this is to install boot-time scripts in /etc/rc*.d. They may also create service-oriented userids, if not already present on the system. (eg: user "mysql" for mysqld)

Announcements

We strongly suggest that all users subscribe to the "announce" list, at http://lists.blastwave.org. This mailing list is for critical CSW/blastwave related announcements only. "Announcements" about new packages of interest, go to the separate newpkgs list.

Release Program

Blastwave offers packages from 2 repositories, called “stable” and “unstable”. Users must choose which group to use.

The “unstable” archive is updated often. Unstable will appeal to users that like to have that very latest versions of software. Due to nature of these rapid releases users must accept there might be packages that have open bug reports applied to them.

The “stable” archive is updated every 3 months, nominally at the beginning of January, April, July and October. The packages that form “stable” are taken from “unstable” but are first proven by use in “unstable” and through a program of QA testing. The packages are known to work together and have all known critical bugs fixed. Should any critical security problem need to be fixed then the “stable” archive will be changed mid-term and due notice of the update given. Stable will suit the business or serious user who expects continuity and reliability of service.

The build procedures for both “unstable” and “stable” are similar, neither archive will have packages with known fatal errors, the difference is the testing, time delay and level of quality assurance of the archives. The names “unstable” and “stable” relates more to the nature of change than the stability of the underlying software. Users must make themselves aware of the quality of the underlying software and make installation choices based this.

To select “stable” or “unstable” , set the “url=” entry in /opt/csw/etc/pkg-get.conf to point to a mirror's “unstable” or “stable” subdirectory.

Users wishing to migrate from “unstable” to “stable” can do so at any time but are advised to do so just before a “stable” release. At that time the packages in “unstable” are at their closest to those in the next “stable” . Changing to “stable” at any other time will mean the installed “unstable” packages are still being used as the “stable” version will lag behind “unstable” and so not retro install. This will correct itself when the “stable” versions catch up which will happen at the next “stable” release.

Upgrade of “stable” is recommended once during each “stable” cycle. Updates from one “stable” to the next are QA tested. Leaving it longer means an update spans more than one release, this is not tested and might cause problems.

Using programs in our packages

Unset LD_LIBRARY_PATH
Most important of all, is to unset your LD_LIBRARY_PATH variable. If you absolutely must have it set for some reason (not recommended), then best results should come if you use
# THIS IS NOT A GOOD IDEA
LD_LIBRARY_PATH='/opt/csw/lib/$ISALIST':/other/values/here
# THIS IS NOT A GOOD IDEA
The single-quotes are required, as is putting the csw entry FIRST.

All blastwave executables have been compiled with the appropriate -R flag, so that they will automatically use the right blastwave libraries by default. LD_LIBRARY_PATH is a tool given to users so that they may choose to deliberately override the built-in library path of executables. If you choose to set LD_LIBRARY_PATH, you have made a specific configuration choice that we cannot override in blastwave CSW packages. So if you use it, keeping things working is on your own shoulders.

Setting your PATH
Put /opt/csw/bin first in your path!! Particularly if you want to compile your own tools against blastwave packages. Sun may also ship its own versions of things like "pkgconfig", as "/bin/pkgconfig". If a configure script sees /bin/pkgconfig first, then at best, you will miss out on features, and at worst, your compiled programs will crash mysteriously.
Most binaries you care about, will be in /opt/csw/bin . There are occasional packages that may have their own subdirectories - for example, /opt/csw/apache . Generally speaking, however, you will only want to add /opt/csw/bin to your PATH.
DO NOT add /opt/csw/bin/sparcv9, or any other subdirectory of /opt/csw/bin, to your PATH. If there is a binary in /opt/csw/bin/sparcv9, there will be an appropriate wrapper in /opt/csw/bin of the same name, that will automatically determine whether to run the the sparcv8 version, or the sparcv9 version, of a program.

FYI: A good place to set the PATH variable for everyone, is in /etc/default/login

Setting your X resource search path
By default, Solaris programs tend to look in under /usr/openwin/lib for what are called "app-default" customization files. Since we dont want to interfere with Solaris directories, we keep ours under /opt/csw. To ensure you get all the CSW customizations, you should set the environment variable XFILESEARCHPATH. We suggest the following setting:

XFILESEARCHPATH=/opt/csw/lib/X11/%T/%N%C:/usr/openwin/lib/X11/%T/%N%C export XFILESEARCHPATH

For long-time X users, please note that the old environment variable XAPPLRESDIR is obsolete, and will not support the use of multiple directory names.
For more details on this variable, and resource files, please see http://www.faqs.org/faqs/x-faq/part2/section-22.html . The full documentation gives extra details on finer points such as making one that is flexible for your locale settings.

Package upgrades

It is hoped that most people will take advantage of the features of pkg-get to be able to simplify upgrading the blastwave packages they have installed, with
pkg-get upgrade
As such, blastwave packages are normally designed to cleanly go through a "pkgrm CSWpkg ; pkgadd CSWpkg" cycle, without destroying any locally generated configuration. If you encounter software that does not cleanly handle an upgrade, please file a bug report against the package.

Sometimes, after upgrading a specific package individually, you may experience errors or problems with that package. Before assuming that that package is broken, please do a general
pkg-get upgrade
without limiting the upgrade to any one package, so that all your packages and libraries are brought up to the current version. This will often fix a perceived problem with a particular package.
Requesting updated software
If you notice that there is a newer version of software available from the original source code site, making a particular blastwave package out of date, please file a bug report against the package. This is really the best way to let the maintainer know a newer version is available. It's also a convenient way to let YOU know when the newer version gets packaged.

Program documentation

There are a few different places you can look for extra documentation or information on a program:

In the directory /opt/csw/share/doc/progname
For simple programs, this directory may not exist. However, for more complex programs, more detailed instructions on configuration and usage may be found here.

From the page http://www.blastwave.org/packages/progname,

Follow the link to the original source site, and browse around

Click the button for "View News and Info"

Relocation from /opt/csw

If for some reason, you cannot mount something in /opt/csw directly, but must symlink /opt/csw to somewhere else, you will probably want to set
  PKG_NONABI_SYMLINKS=true
in your environment. This is to avoid the system-level pkgadd changing /opt/csw into a real directory. However, the preferred method is to use a lofs mount:
eg: mount -F lofs /export/home/opt /opt/csw
Please note that it is not possible to completely relocate the software to elsewhere, and have /opt/csw not exist. Some programs require directory paths to be compiled into them, which means they will reference /opt/csw/[...] explicitly.

Tips for large scale deployments

Sites that are interested in deploying CSW packages on a large scale, will probably wish to read our page on sharing the /opt/csw filesystem

Mailing lists

There are user-oriented mailing lists available, on lists.blastwave.org. Currently, there are lists available for general user questions, new package annoucements, and site announcements.

Top level - https://lists.blastwave.org/mailman/listinfo

FAQs (aka "Why Do You Do That????")

We now have a Frequently Asked Questions page

Contents