Correctly rename the new urpmihowto manpage4.8.23

1 files changed, 402 insertions, 0 deletions

diff --git a/pod/urpmihowto.8.pod b/pod/urpmihowto.8.pod
new file mode 100644
index 00000000..992188a1
--- /dev/null
+++ b/pod/urpmihowto.8.pod
@@ -0,0 +1,402 @@
+=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 C<http://>, C<ftp://>, C<rsync://>, C<ssh://> (this
+will use rsync over ssh), C<file://>, and C<removable://> (C<removable://>
+works like C<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:
+
+    <scheme>://<login>:<pass>@host/path
+
+Those credentials won't be stored in any world-readable file.
+
+In some cases, if your media points at an external HTTP or FTP server, you
+might want to use a proxy to access it. This is possible by using the
+C<--proxy> and C<--proxy-user> options (the second one in case of your
+proxy requires authentication.)
+
+=head2 Removing media
+
+This is straightforward; to remove a media C<foo>, simply use the
+command:
+
+    urpmi.removemedia foo
+
+=head2 Updating media
+
+Some media never change; this is the case, for example, for CD-ROMs and
+the like. However, some other ones -- typically updates -- grow; new RPMs
+are added to them, and old ones are removed. Thus, before using them, from
+time to time, you should instruct urpmi that their contents might have
+changed.
+
+To do this, use the urpmi.update program. You can either update all media:
+
+    urpmi.update -a
+
+or update only media specifically named:
+
+    urpmi.update updates-one updates-two
+
+=head2 Creating your own media
+
+The easiest way to create your own media is to let urpmi.addmedia do it.
+However, this will work well only if you have a small number of rpms,
+stored on disk or on a shared NFS mount. To do that, assuming that your
+RPMs are under a directory /var/my-rpms, simply enter the command:
+
+    urpmi.addmedia my-media /var/my-rpms
+
+However, to create media containing a large number of RPMs, or to be put
+on a shared server, you'll need to use the gendistrib tool. It comes in
+the C<rpmtools> package. It is able to generate a mirror tree for one or
+several media.
+
+A typical media repository, under a root directory F</ROOT/>, has the
+following structure: (here, we have two media, named C<first> and
+C<second>)
+
+    ROOT/ - media/
+            |- first/
+            |   `- media_info/
+            |- second/
+            |   `- media_info/
+            `- media_info/
+
+The RPMs are place in the C<first> and C<second> subdirectories.
+Repository metadata is contained in the top-level F<media_info> directory.
+Per-media metadata are contained in the F<first/media_info> and
+F<second/media_info> subdirectories.
+
+Per-media metadata consists in an C<hdlist.cz> file, that contains the
+gzipped headers of the RPMs in the media, a C<synthesis.hdlist.cz> file,
+much smaller than the hdlist and that contains only the information
+necessary to urpmi to resolve dependencies, and optionnally a C<pubkey>
+file if the RPMs are signed (so urpmi can check that the RPMs it downloads
+are signed with the key associated to this media.)
+
+Before using F<gendistrib>, you must create a file F<media_info/media.cfg>
+to describe this media repository. The syntax of this file is reminiscent
+of F<.ini> files. It contains one section per media: for example,
+
+    [first]
+    hdlist=hdlist_first.cz
+    name=First supplementary media
+
+Here, C<first> is the directory name, C<hdlist_first.cz> is the name of
+the hdlist file that will be created (it must end with C<.cz>), and
+C<name=> gives a human-readable descriptive name for the media.
+
+Then, you can run gendistrib. It should be passed the F</ROOT/> directory as
+parameter. It will then generate the hdlist and synthesis files and all
+other files needed for proper repository operation.
+
+For further information, see the gendistrib(1) manpage.
+
+=head1 Searching for packages
+
+=head2 urpmf
+
+urpmf is a grep-like tool for the urpmi database (the database of all RPMs
+in the media). By default, it will search through the file names contained
+in packages, but a variety of options allows to search through package
+names, provides, requires, RPM descriptions, etc. (or several of those at
+once.)
+
+For example, to find all packages that begin with "apache-" :
+
+    urpmf --name '^apache-'
+
+(the ^ being the beginning-of-line anchor used in standard regular
+expressions.)
+
+To find all packages that contain files whose pathname includes
+/etc/httpd.conf.d :
+
+    urpmf /etc/httpd.conf.d
+
+To find all packages that provide "mail-server", with their version and
+release number (-f) :
+
+    urpmf --provides -f mail-server
+
+See the urpmf(8) manpage for more examples and the list of all options.
+
+=head2 urpmq
+
+urpmq is a tool to query the urpmi database. It has several modes of
+operation. Here are a couple of useful uses.
+
+    urpmq -i package
+
+will list the information for that package (like C<rpm -qi> would do for
+installed packages.) The C<--summary> option is similar, but gives only
+one-line concise information.
+
+    urpmq --source package
+
+will give the URL from which the package can be retrieved.
+
+    urpmq -d package
+
+will give the list of all RPMs that are required by the specified package
+(recursively).
+
+Inversely, the command
+
+    urpmq -R package
+
+will give the list of all RPMs that require the specified package.
+
+See the urpmq(8) manpage for the list of all options.
+
+=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