Trying ARK (sample1)

Hosted by

Trying the Arusha Project, `sample1'-style

OK, you want to try out this Arusha Project stuff. This document tells you one way you can do that.

It's worth repeating: the Arusha Project is about helping `teams' of sysadmins to collaborate, leading to better systems for all. It's a framework -- it's not ``run this code and you're done''.

The ``test drive'' described here is simply to let you see some ARK stuff in action. You shouldn't need superuser (or other special) privileges. You can do it in your home directory (assuming enough disk space).

Being on at least one ARK mailing list

We heartily recommend being on one or more of the ARK mailing lists. [It is Generally Wise to monitor (at least) the major electronic forum for all major sysadmin tools that you use.]

All of the mailing lists have archives back to their inception. A tarball of old messages is also available on request.

Questions? (now or later...)

If you have any questions about this Arusha-trying process, or which arise from your trying it, please pipe up on the ark-dev mailing list! You are not alone with your questions, we promise.

If you're feeling really shy (but you shouldn't), send your questions/comments to any one of the core developers.

Getting and unpacking the Arusha code

Check the downloads page. The CVS repository will always be the most up-to-date. It may be simpler, however, to use a single set of downloadable-able snapshots, e.g. ark-*-20021001.tar.gz.

Stuff for the most-complete site (`verilab2') -- useful for study -- is only available as a SourceForge download. You don't have to have it for the experiment below, but it's a handy reference.

Unpack all of what you've got in an ``Arusha source'' area, anywhere you like; e.g.:

% mkdir $HOME/ark-src
% cd $HOME/ark-src
% for i in /wherever/ark-*-20021001.tar.gz ; do gzip -dc < $i | tar xf - ; done

Give a name to where to plopped the stuff; for example:

% ARK_SRC=$HOME/ark-src/ark-20021001; export ARK_SRC

Creating your own `team' (site)

You now need to set up a `team' for your site, putting the "source" for your team's configuration in $ARK_SRC (along with all the other teams):

% cd $ARK_SRC
% mkdir myteam1

For this exercise, we suggest you "seed" your team from the `sample1' team, which is a team that does stuff The Sidai Way. (`sidai' is an Arusha "policy" team.) Here's a sample "seeding":

% cd $ARK_SRC/sample1
% tar cf - . | ( cd ../myteam1 && tar xfv - )

You WILL need to change things in `myteam1' before you can try it. That's later...

Getting/installing the prerequisite tools

We suggest you try your Arusha setup on just one host, perhaps a Solaris box. On that one machine, you will need one or two tools, and could probably do with some others.

We do not yet have the resources to say, ``Just get these bit-blobs from us at...'' However, please see our platform-by-platform crib sheet about prerequisite tools (what you need, how to get 'em, how to install them) -- do what it says!

Getting the other source code you will need

By default, the `sample1' team (and, therefore, your clone of it...) sets out to build the following packages:

% cd $ARK_SRC/myteam1/package
% ls *.xml|egrep '[0-9]'
gzip--1.3.5.xml
coreutils--5.2.1.xml
rsync--2.6.4.xml

These versions are arbitrary. If you prefer a different one, just rename the relevant file in the obvious way, and edit the version number inside it, too (again obvious).

The `gzip' and `coreutils' packages (NB: formerly `textutils') are required, because gzip and md5sum are used internally by Sidai-style ARKing. If you're using a machine that includes those tools, you can do without these packages. Here, we're building rsync ``just for fun''.

Whatever packages you decide to build, you need to have the source tarballs for them. Stash them all in one place, which we will hereafter refer to as $OPEN_SRC.

The packages listed above come from:

gzip: ftp://alpha.gnu.org/gnu/gzip/ (or ftp://ftp.gnu.org/gnu/gzip/, if you prefer the old version 1.2.4a).
coreutils: ftp://ftp.gnu.org/gnu/coreutils/
rsync: ftp://rsync.samba.org/pub/rsync/

Creating an `ARK profile'

You will need to create a small `ARK profile' file; $HOME/.ark_profile is a reasonable name, and it looks like:

team = myteam1

repository[ARK]      = /workspace/partain/ark/ARK
repository[myteam1]  = /workspace/partain/ark/myteam1
repository[sidai]    = /workspace/partain/ark/sidai

As you can see, the file simply says what (site) team you're operating as (myteam1) and where to find the local copy of source bits for all teams; i.e. $ARK_SRC is /workspace/partain/ark in this case.

Don't forget a repository entry for your own team!

Next thing: export ARK_PROFILE=$HOME/.ark_profile (C-shell: setenv ARK_PROFILE ~/.ark_profile). (ARK code dies immediately if you haven't set this environment variable.)

Customizing your `team' for your site

You created a `team' earlier (we called it myteam1). Its configuration needs to be an accurate reflection of your setup.

team.xml (most basic info about your team/site)

You need to change the *** CONFIGURE ME *** section.

<test-dir>: A directory where ARK can put all of its working directories; you can delete it when you're done playing.
<ark-src-dir>: Set to what you had for $ARK_SRC above; i.e. what your put in your ARK_PROFILE for where your local copies of ARK teams' source is.
<open-src-dir>: Where you stashed your open-source packages' tarballs; we called it $OPEN_SRC before.
<solo-host>: The name of the single host you are going to try ARK on. (See the next part about hosts...)
<solo-host-type>: The name of the proto-host which represents the type of machine that <solo-host> is. (See the next part about hosts...)

host/ (info about hosts at your site)

You'll need:

One XML file for your <solo-host>, which will look very much like the one we supplied for `slicker' in sample1/host/.
Be sure to get rid of host/slicker.xml (unless you have a machine named 'slicker').
An XML file for your <solo-host-type> proto-host. It will probably look very much like the one we supplied in sample1/host/sparc-solaris.xml.
An XML file for proto-host `ALL'. The one we supplied in sample1/host/ALL.xml should do nicely.
Be sure to read this file and change <ARK-BUILDING-PATH> if you have programs in nonstandard locations. ARK will do builds using <ARK-BUILDING-PATH>, not by inheriting the PATH of the calling environment.

package/ (info about packages at your site)

We discussed this earlier... It shouldn't require changing, unless you want to adjust versions-to-build...

Test drive with `try-ark`

Try the try-ark script, perhaps as follows:

% cd $ARK_SRC/myteam1
% try-ark/try-ark | tee /tmp/try-ark.out

(The tee business is so you'll have a handy full copy of what happened...)

It first attempts a few sanity checks. It will grumble (in a somewhat unfriendly manner) until all is well.

Once try-ark really gets going, it will build/install/deploy/reveal the (real) packages in myteam1/package/*.xml for your one-host site.

If all goes well, it will end (sadly...) with a message something like...

ark-site-gen: status problem on `reveal' method:
   ark-site-gen: `installed' not among: revealed

That's cool. (We could explain why, but then we would have to kill you...)

Should you want to say ``Go back and start again'', just do ./try-ark --scrub.

You should be able to delete your <test-dir> directory (holding all the ARK-generated artifacts) without any problem. I.e. rerunning try-ark will remake everything.

More packages?

Well, if you found building gzip, coreutils, and rsync entertaining, you could always try a bunch more! The simplest way would be to grab a `verilab2' (team) tarball (SourceForge download), copy over a package (or ten) of interest, and run try-ark again. That would be:

cd $ARK_SRC
cp verilab2/package/interest--1.2.xml myteam1/package/
try-ark

Standard freeware packages should be pretty easy, e.g. (GNU) `m4', GNU make, patch, perl, shtool, texinfo, bison, flex, zlib, ...

You should probably stay away from any rootly packages (e.g. `sudo', `tcpwrappers', ...) and/or any of the packages associated with configuring them (many of the `*-config' packages).

In messing with this stuff, you may well bump into some walls (not to mention bugs...), but you are unlikely to harm anything.

Where next?

This may be a good time to think over ways to use ARK, and/or to consider the Sidai team's strategy for becoming a full-blown Sidai-style site (NB: a common direction).

Remember, only a tiny fraction of ARK-style sysadmin potential has even been thought of so far, never mind done. Please tune in to the ARK community and let's work together to do some Very Cool stuff.