From 631d1555596c82094401ecef01985628dd477eb0 Mon Sep 17 00:00:00 2001 From: Rafael Garcia-Suarez Date: Fri, 11 Aug 2006 08:41:31 +0000 Subject: Correctly rename the new urpmihowto manpage --- MANIFEST | 2 +- pod/urpmihowto.8.pod | 402 +++++++++++++++++++++++++++++++++++++++++++++++++++ pod/urpmihowto.pod | 402 --------------------------------------------------- 3 files changed, 403 insertions(+), 403 deletions(-) create mode 100644 pod/urpmihowto.8.pod delete mode 100644 pod/urpmihowto.pod diff --git a/MANIFEST b/MANIFEST index d3ca49aa..cb20da4f 100644 --- a/MANIFEST +++ b/MANIFEST @@ -29,7 +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/urpmihowto.8.pod pod/urpmq.8.pod pod/fr/urpmi.fr.8.pod po/el.po 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. 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 + +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, 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 + +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 + +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. 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] [with ] + +In this synopsis, C<< >> is the name of the new media, +C<< >> the URL where the RPMs are to be found, and the C +parameter optionnally specifies where to find the information file that +describes the media's contents. + +Supported URLs can be C, C, C, C (this +will use rsync over ssh), C, and C (C +works like C, 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: + + ://:@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, 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 package. It is able to generate a mirror tree for one or +several media. + +A typical media repository, under a root directory F, has the +following structure: (here, we have two media, named C and +C) + + ROOT/ - media/ + |- first/ + | `- media_info/ + |- second/ + | `- media_info/ + `- media_info/ + +The RPMs are place in the C and C subdirectories. +Repository metadata is contained in the top-level F directory. +Per-media metadata are contained in the F and +F subdirectories. + +Per-media metadata consists in an C file, that contains the +gzipped headers of the RPMs in the media, a C file, +much smaller than the hdlist and that contains only the information +necessary to urpmi to resolve dependencies, and optionnally a C +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, you must create a file F +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 is the directory name, C is the name of +the hdlist file that will be created (it must end with C<.cz>), and +C gives a human-readable descriptive name for the media. + +Then, you can run gendistrib. It should be passed the F 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 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 is the name of the alias you'll use to specify +the network to urpmi, C is the install method (to use C, 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 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 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 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 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 + +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 + +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. 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 diff --git a/pod/urpmihowto.pod b/pod/urpmihowto.pod deleted file mode 100644 index 992188a1..00000000 --- a/pod/urpmihowto.pod +++ /dev/null @@ -1,402 +0,0 @@ -=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. 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 - -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, 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 - -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 - -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. 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] [with ] - -In this synopsis, C<< >> is the name of the new media, -C<< >> the URL where the RPMs are to be found, and the C -parameter optionnally specifies where to find the information file that -describes the media's contents. - -Supported URLs can be C, C, C, C (this -will use rsync over ssh), C, and C (C -works like C, 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: - - ://:@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, 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 package. It is able to generate a mirror tree for one or -several media. - -A typical media repository, under a root directory F, has the -following structure: (here, we have two media, named C and -C) - - ROOT/ - media/ - |- first/ - | `- media_info/ - |- second/ - | `- media_info/ - `- media_info/ - -The RPMs are place in the C and C subdirectories. -Repository metadata is contained in the top-level F directory. -Per-media metadata are contained in the F and -F subdirectories. - -Per-media metadata consists in an C file, that contains the -gzipped headers of the RPMs in the media, a C file, -much smaller than the hdlist and that contains only the information -necessary to urpmi to resolve dependencies, and optionnally a C -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, you must create a file F -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 is the directory name, C is the name of -the hdlist file that will be created (it must end with C<.cz>), and -C gives a human-readable descriptive name for the media. - -Then, you can run gendistrib. It should be passed the F 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 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 is the name of the alias you'll use to specify -the network to urpmi, C is the install method (to use C, 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 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 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 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 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 - -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 - -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. 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 -- cgit v1.2.1