=head1 NAME

urpmihowto - urpmi Advanced How-To

=head1 Basic notions

=head2 Packages and media

The urpmi suite of tools has for main purpose to download and to install
RPM packages easily.

Software packages often depend on each other; urpmi is able to recognize
those dependencies, to download missing required packages as needed, and
to remove conflicting packages if it needs to.

urpmi gets the list of available RPMs, and the RPMs themselves, from a
B<media>. Roughly speaking, a media is described by a name and by a
location, specified by an URL. Currently supported media types are: local
drives, removable drives (such as CDs), ISO images, and networked media
via different protocols (http, ftp, ssh and rsync). NFS mounted
directories are treated like local drives.

=head2 Installing and updating RPMs

The tool used to install RPMs is urpmi. Its basic usage is as follows:

    urpmi <list of package names>

That prompts urpmi to fetch and install all packages and their unmet
dependencies from the media you have configured. In the process, urpmi
might ask a few questions. Notably, if some packages need to be upgraded,
or if some new (unspecified) packages should be installed, it will ask for
confirmation. If some packages need to be removed (due to conflicts with
the requested packages), urpmi will ask for confirmation as well. In some
cases, urpmi will also propose a choice between different alternatives,
usually proposing the "best" package as a default.

Another very useful mode of action for urpmi is to ask it to upgrade all
packages to the latest version found on the media. This is done by

    urpmi --auto-update

urpmi can also help installing RPM files directly. Instead of using
C<rpm -i foobar.rpm>, you can pass the path to the rpm file to urpmi: it
will then try to resolve the needed dependencies.

Useful options to urpmi include :

=over 4

=item --auto

automatic mode: urpmi will not ask questions and always select the default
choice.

=item --test

tests the installation of packages, but do not actually install anything or
modify the system.

=item --media I<media1,...,mediaN>

Use only the specified media, instead of defaulting to all available
media. You can also specify a substring of media names, and urpmi will
select all media that contain this substring. (For example,

    urpmi --auto-update --media updates

will search updates from all media that have "updates" in their name.)

=back

See the urpmi(8) manpage for the complete reference of all options that
urpmi supports.

=head2 Removing RPMs

The tool used to deinstall RPMs is urpme. The command

    urpme <list of package names>

will attempt to remove all listed packages, plus the packages that depend
on them. It will refuse to uninstall "important" packages (that is, the
ones that are part of the base system.)

See the urpme(8) manpage for the reference of all options urpme supports.

urpme isn't able to detect packages that are no longer used: for example,
libraries that no application requires. To clean them up, a handy tool is
B<rpm-find-leaves>. It will list all RPMs on your system that no other
package requires.

=head1 Media management

=head2 Adding media

urpmi is usable only when you have defined some media. Usually the OS
installation procedure configures a predefined set of media, which
correspond to the installation method you've selected: that might be
installation CDs, or an HTTP or FTP server if you installed from a
networked mirror, and so on. But you might want to add media yourself.
For that, you should use the urpmi.addmedia program. Its usage is as
follows:

    urpmi.addmedia [options] <name> <url> [with <hdlist>]

In this synopsis, C<< <name> >> is the name of the new media,
C<< <url> >> the URL where the RPMs are to be found, and the C<with>
parameter optionnally specifies where to find the information file that
describes the media's contents.

Supported URLs can be http://, ftp://, rsync://, ssh:// (this will use rsync over
ssh), file://, and removable:// (removable:// works like file://, but
instructs urpmi that the directory is mounted from a removable media, such
as a CD or a DVD.) If the media requires authentication, you can use the
usual URL syntax: C<< <scheme>://<login>:<pass>@host/path >>. Those
credentials won't be stored in any world-readable file.

=head2 Removing media

=head2 Updating media

=head2 Inactive media

=head2 Creating your own media

gendistrib

public key

=head1 Searching for packages

=head2 urpmf

=head2 urpmq

=head1 urpmi-parallel

urpmi-parallel is an add-on to urpmi that is useful to install packages on
a network: it will run an urpmi command in parallel on a specified number
of hosts. In more detail, the machine you run the command on (the
"server") tests its result on each machine in the group in turn (the
"clients"), downloads all necessary packages for all machines in the
group, distributes the appropriate packages to each machine, then calls
urpmi on the machine to do the actual installation.

urpmi must be installed on all client machines, but it is not necessary to
have media defined on these.

To use it, follow those steps :

=over 4

=item *

make sure you can ssh from the server to each client machine as root (you
can use ssh-add on the server host to avoid entering your passphrase
and/or password many times).

=item *

install urpmi-parallel-ssh and/or urpmi-parallel-ka-run on the server
machine. The first plugin uses plain ssh to distribute commands to other
hosts, the second one uses ka-run, an efficient parallelization method on
top of any remote shell (rsh or ssh), adapted to clusters.

=item *

Edit /etc/urpmi/parallel.cfg to look something like this:

    mynetwork:ssh:host1:host2:host3

On this line, C<mynetwork> is the name of the alias you'll use to specify
the network to urpmi, C<ssh> is the install method (to use C<ka-run>, look
up the entry for /etc/urpmi/parallel.cfg in urpmi.files(5)), and hostN are
the hostnames of all clients on your network. You can put C<localhost> in
this list.

=item *

Run the urpmi command : for example, to install "package_name" :

    urpmi --parallel mynetwork package_name

=back

=head1 urpmi.recover

urpmi.recover is a tool to help management of RPM rollbacks. One rarely
used feature of RPM is that it can "repackage" the RPMs it deinstalls
(either because they are upgraded to a newer version, or because they are
plainly erased), and then reinstall the repackaged RPMs, thereby restoring
the system to a previous (hopefully more stable) state.

urpmi.recover has three main functions:

=over 4

=item define a checkpoint

C<urpmi.recover --checkpoint> is used to define a point in your system
that you consider stable, and to start storing info that will enable you
to rollback to this state (or to any later state).

=item list installations you've done

C<urpmi.recover --list date> is used to list chronologically all
installations and upgrades on your system up to the specified date. The
output format gives them grouped by installation transactions. (This
option has two variants, C<--list-all> and C<--list-safe>.) Here are some
examples :

List all installations made during the last day :

    urpmi.recover --list '1 day ago'

List all installations since 7th february 2006 :

    urpmi.recover --list 2006-02-07

List all installations since the checkpoint :

    urpmi.recover --list-safe

Lists all installations and upgrades known to the RPM database :

    urpmi.recover --list-all

=item perform rollbacks

C<urpmi.recover --rollback> is used to roll back installations and
upgrades to a previous point in the past (at most until your checkpoint.)
It has two variants :

To roll back until a specified date :

    urpmi.recover --rollback <date>

The date can be a duration (for example "2 hours ago") or a date given
in YYYY-MM-SS hh:mm format.

To roll back a specified number of transactions :

    urpmi.recover --rollback <number of transactions>

In both cases, be careful not to rollback beyond the checkpoint!

=back

Once you've defined a checkpoint, when you use urpmi, urpme or directly
rpm to install or remove packages, the older packages will be stored in
/var/spool/repackage. You thus must make sure you have enough space on
this partition to store all repackaged RPMs.

Technically, defining a checkpoint is equivalent to writing a file
/etc/rpm/macros.d/urpmi.recover.macros that overrides the rpm macros
used to set up the repackaging functionalities of rpm. You can change
C<%_repackage_dir> there if you want to, if you don't want to store
repackaged RPMs in /var/spool/repackage.

If you want to disable the repackaging functionality and clean up the
repackage spool, use C<urpmi.recover --disable>. Warning: rollbacks won't
be possible anymore.

=head1 Restricted urpmi

urpmi has a "restricted" counterpart: rurpmi. It is similar to urpmi, but
has a stripped-down set of features. It's intended to be used by users
without root privileges, but with sudo rights on it, preventing any abuse
of this tool to compromise the system.

Its syntax is similar to the one of urpmi, but it disallows installing
arbitrary RPMs: those are forcibly downloaded from a registered media.
A number of dangerous options, listed in the rurpmi(8) manpage, are also
forbidden.

=cut