Usage information for Yam and a description of the options and config file
==========================================================================

yam is used to create a repository on your server from multiple sources.


Finding help on the command line
--------------------------------
yam -h
usage: yam [-g] [-q] [-u] [-v] [-c config] dist1 dist2-arch
Set up a distribution server from ISO files

Yam options:
  -c, --config=file     specify alternative configfile
  -g, --generate        generate Yam repositories
  -q, --quiet           minimal output
  -u, --update          fetch OS updates
  -v, --verbose         increase verbosity (only Yam info)
  -vv, -vvv             increase verbosity more
      --unmount         unmount distributions


When you first run yam, do:

	yam -v

This will show you what it is doing. You may add extra -v at any time
to see more of Yam's internals.

	yam -vvv

Now, you may want to change the default yam.conf to your needs and
add or remove distributions and/or repositories. If you have ISO
images of any of the distributions you want to mirror, mention them
too like in the examples, and copy them over to /var/yam/iso
(You can also decide to put them per distribution/arch)

The default directory structure that Yam uses is explained in
README.dirs

Yam by default will mount as many ISO files as possible. If you
have problems with the maximum number of loop devices, please read
README.loop

Yam can also download the distribution RPM packages if you want to,
if you did not specify any ISO images it will download any os or core
repositories that you have specified. To do that, do

	yam -u
or
	yam -uv

To finally generate a complete working repository based on the
repositories, you need to issues:

	yam -g
or
	yam -gv

This will look for all the necessary packages in /var/yam (srcdir) and
symlink them to /var/www/yam (wwwdir). /var/www/yam can also be removed
at any time and should not contain any files you have put there yourself.

To start off from scratch, first unmount the ISO images by doing:

	yam --unmount

and then remove /var/www/yam completely. This should never be needed,
but can be done after you played around or when removing components.

If you want to update only a part of your repository, you can select
the distributions by doing:

	yam -ugv fc2
or
	yam -ugv fc2-i386
or even
	yam -ugv fc2-i386 fc1-x86_64

If you want to have multiple setups of Yam running on a single system
(say one of your users wants its own setup), you can specify an
alternative config file, by doing:

	yam -c /home/dag/yam.conf

In that case the user may want to use another srcdir and wwwdir.

Finally, you can see if everything worked, by looking at /var/www/yam
(wwwdir) or by surfing to http://localhost/yam/. For more information
about web-access and configuration, see README.web


The yam.conf file
-----------------
yam.conf file holds all the information yam uses to find the repos such
as distribution information and URLs to the repos.  yam.conf is essentially
divided into three areas.  main, repos, and dist.

The main area is your main configuration for yam.
Example from default yam.conf:

	[main]
	srcdir=/var/yam
	wwwdir=/var/www/yam
	metadata=apt repomd
	arch=i386

The srcdir is where yam will download and store the files for your repo

The wwwdir is the location as to where your users for your repo will actually
get the files from. These are symbolic links to the srcdir.

The metadata is a list of metadata repositories you want to create. This
defined the default used if nothing is specified per distribution.

arch is a list of the default architectures, i.e.  i386, x86_64.
This will set it globally but can be configured per distro.

The distro area of yam.conf is the heart of yam.conf it is where you can
specify the exact distribution and URLs to download from. Let me demonstrate
with a little example:

	[fc3]
	name = Fedora Core $release ($arch)
	release = 3
	arch = i386 x86_64
	iso = FC$release-$arch-disc?.iso
	core = rsync://ayo.freshrpms.net/pub/freshrpms/pub/freshrpms/ayo/fedora/linux/$release/$arch/RPMS.$repo/
	updates = rsync://ayo.freshrpms.net/pub/freshrpms/pub/freshrpms/ayo/fedora/linux/$release/$arch/RPMS.$repo/
	rpmforge = rsync://apt.sw.be/pub/freshrpms/pub/dag/fedora/$release/en/$arch/RPMS.dag/
	freshrpms = rsync://ayo.freshrpms.net/pub/freshrpms/pub/freshrpms/ayo/fedora/linux/$release/$arch/RPMS.$repo/
	newrpms = rsync://newrpms.sunsite.dk/projects/newrpms/www/htdocs/apt/redhat/en/$arch/fc$release/RPMS.$repo/

The section name [fc3] is your dist tag and you can change it to fit your needs.  
Other tags you can include per section are:

	name = is a description for this distribution ($name)
	release = is the release version of your distribution ($release)
	metadata = is a list of metadata you want for this repo
	arch = is set to one or more architectures available for this distribution ($arch)
	iso = is set to one or more globs matching the distributions ISO images

Any other entries are considered to be repositories. Yam will assume that
repositories called 'os', 'core' and 'updates' are base system repositories
and these will be updated with Yam option -u . os and core repositories will
be ignored when ISO images are available.

Other entries are considered extra (3rd party) repositories. Yam will create
a separate directory for each of these in /var/yam/$dist-$arch/$repo
The LHS part can also be used in the RHS as variable $repo

Other special variables include:

	$srcdir	is set to the srcdir variable from yam.conf
	$dist 	is set to the distribution section name (eg. fc2)
	$arch	is set to the architecture within this section context
	$nick 	is set to $dist-$arch within this section context
	$repo 	is set to the current repo-name within this repo context

Yam can use several types of protocols or URL identifiers:

	<empty>		- use the directory in $srcdir/$dist-$arch/$repo
	file://		- handled by yam, symlink to other directory containing RPMS
	fish://		- handled by lftp
	ftp://		- handled by mirrordir or lftp
	http://		- handled by lftp
	https://	- handled by lftp
	mc://		- handled by mirrordir
	rhn://		- handled by up2date python classes
	rhns://		- handled by up2date python classes
	rsync://	- handled by rsync
	sftp://		- handled by lftp
	yam://		- handled by yam, equivalent to file://$srcdir/


Metadata for repositories
-------------------------
Depending on what repositories you want to generate, you can install
a combination of these packages:

	keyword		description		package
	"""""""		"""""""""""		"""""""
	apt		for apt 0.5.15cnc	binary 'genbasedir' inside 'apt' package

	yum		for yum < 2.4		binary 'yum-arch' inside 'yum' package

	repomd		for apt >= 0.5.15lorg	binary 'createrepo' inside 'createrepo' package
			and yum >= 2.4

---
Please send me improvements to this document.
