First draft of an urpmi advanced How-To

2 files changed, 192 insertions, 0 deletions

diff --git a/MANIFEST b/MANIFEST
index e919cdd9..88849774 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -29,6 +29,7 @@ pod/urpmi.files.5.pod
 pod/urpmi.recover.8.pod
 pod/urpmi.removemedia.8.pod
 pod/urpmi.update.8.pod
+pod/urpmihowto.pod
 pod/urpmq.8.pod
 pod/fr/urpmi.fr.8.pod
 po/el.po
diff --git a/pod/urpmihowto.pod b/pod/urpmihowto.pod
new file mode 100644
index 00000000..3c95e34a
--- /dev/null
+++ b/pod/urpmihowto.pod
@@ -0,0 +1,191 @@
+=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.
+
+=head2 Removing RPMs
+
+The tool used to deinstall RPMs is urpme.
+
+=head1 Media management
+
+=head2 Adding media
+
+=head2 Removing 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