Using the `ark' tool

Synopsis

ark<type> <method> [options] <thing-1> [<thing-2> ...]

% ark package build --verbose coreutils--5.2.1
% ark package announce --format=html xemacs--21.1.10 emacs--20.7
% ark package verify --hosts=. ALL
% ark package uninstall --pretend gcc--2.7.2

General description

In reality, you'll do package- and host-stuff just like we do, and so this description will probably help.

So: package and host are the <type>s you are most likely to manipulate... many others possible, of course.

The <method>s that you invoke will likely be those of the Sidai host and package management schemes... Other Sidai schemes which have (some?) documentation are mailing lists and users.

The quickest way to get a snapshot of the options in play is to run ark --help. Some of the more common and/or involved options are explained in the options section.

The <thing>s on which the <method> is to be invoked can be either `real' things or proto-things. In the package examples above, coreutils--5.2.1 is presumably a real package. ALL is almost certainly a proto-package, presumably one which expands out to all real packages at the site.

By default, methods are run on as many hosts as it takes to complete the task across the whole site. Thus, something like ark package verify ALL will (in all probability) run the verify code on all hosts at the site, potentially a lot of work.

Yes, there are options to constrain the hosts used...

Exit status

Environment variables

The ARK_DEBUG environment variable can be used to turn on debugging bits. I'm sure they're documented somewhere... I almost always use ARK_DEBUG=15.

The DISPLAY environment variable is transmitted to jobs running on remote hosts.

Other variables, e.g. PATH, are not transferred to jobs on remote hosts. That environment is constructed from facts in the ARK database; e.g. for a package method, from the ARK-BUILDING-PATH field.

Options

Common options

--help:

Spit out usage message and exit.

--verbose:

Be that way.

--quiet:

Be even more shy and reticent than usual.

--pretend:

Say what you'd do but don't actually do it. (Like make -n.)

--keep-going:

Keep going even if some method code fails. Not a good idea, really. (Like make -k.)

--version:

Report the version number and exit. (NOT IMPLEMENTED YET)

Constraint-controlling and state-recording options

--use-deps=...:

Set the level of constraints (dependencies) to pay attention to.

The choices are none (ignore all constraints completely), min (essential constraints only), norm (min plus normal constraints---the default, by the way...), or max (norm plus optional constraints).

You probably need to know what you're doing to use --use-deps.

--redo:

Ignore the fact that stateful methods have already been done. Almost invariably used with --use-deps=none.

--dont-record-action:

Used internally; have never had reason to use it in person.

Host-related options

ark package compile ALL

Sometimes that's a bit much. When developing, for example, we may be fairly happy for ARK activity to range across machines. However, for a machine's overnight cron jobs, you probably want activity to stay confined to that machine.

You can limit the set of hosts with the --hosts command-line option. Examples include: --hosts=. (the host I'm running ark on), --hosts=sparc-solaris (all real hosts that have .:sparc-solaris as a prototype), and so on.

It is very common to use --hosts=. when you're trying things out.

The only issue left is ``jumping proxy hosts''... Let's imagine you're running: ark package reveal --hosts=foo wibble. You hit a constraint on a method that turns out to have a proxy-host of bar. Bearing in mind that --hosts is trying to limit activity to host foo, do you run the code for the method, or do you bail out?

Well, normally you do want to run it, because that's the straightforward and obvious `get on with it' thing to do. However, this puts us in danger of --hosts being pointless.

The thing to understand is that --hosts specifies the hosts for which the specified method is to be run, and that the --proxy-hosts method specifies other hosts that are ``acceptable hosts to use along the way''.

The default for --proxy-hosts is ALL. If you want to constrain the hosts on which you might run something, then set --proxy-hosts to something else. For example, in a cron job that is only supposed to affect one machine, you might well do `--hosts=. --proxy-hosts=.'.

ToDo: --down-hosts

Options related to running backwards (undoing)

--hard-undo:

Methods may take away stuff from users. By convention, Sidai-style unreveal, undeploy, and uninstall methods leave programs/etc. that are user-visible as they are (so that can still be used).

Options related to interactive and dangerous methods

--timid-reveal:

A 'reveal' method normally just blazes away and does what it's told. If you want it to be more circumspect, use --timid-reveal. Typical usage would be: use the --timid-reveal flag and, if it stumbles over anything, investigate. Once satisfied, run without the flag.

--interactive:

Run methods marked as interactive; normally we `defer' them.

--dangerous:

Run methods marked as dangerous; normally we `defer' them. This is typically used for methods that apply OS patches and the like.

Site customization