Author: jsmith
Update of /cvs/docs/yum-software-management/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv26309
Modified Files:
yum-software-management.xml
Added Files:
concepts.xml configuring-repositories.xml customizing-yum.xml
introduction.xml isolated-install.xml manage-with-yum.xml
pirut.xml pup.xml search-with-yum.xml tools.xml
update-with-yum.xml yum-caching.xml yum-proxy.xml
Log Message:
Checking in new version of this doc
--- NEW FILE concepts.xml ---
<?xml version="1.0"?>
<section id="sn-Concepts">
<title>Software Management Concepts</title>
<para/>
<section>
<title>About Packages</title>
<para>Fedora software and documentation is supplied in the form of files called
RPM <emphasis>packages</emphasis>. Each package is a compressed archive
containing product information, program files, icons, documentation and management
scripts. Management applications use these files to safely locate, install, update and
remove software. For example, the Fedora installation process uses the packages supplied
with Fedora to build or upgrade a system to your requirements. </para>
<para>Packages also include a digital signature to prove their source. Software
management utilities verify this digital signature by using a GPG <emphasis>public
key</emphasis>. The <code>yum</code> and <code>rpm</code>
utilities share a common <emphasis>keyring</emphasis> that stores all of the
public keys for approved package sources. The system administrator configures these
approved package sources. </para>
<note>
<title>All Fedora Packages are Free and Open Source Software</title>
<para> All of the software provided by the Fedora Project is Free and open
source software. You may download and install Fedora packages on as many systems as
desired. </para>
</note>
</section>
<section>
<title>About Repositories</title>
<para>A <emphasis>repository</emphasis> is a prepared directory or
Web site that contains software packages and index files. Software management utilities
such as <code>yum</code> automatically locate and obtain the correct RPM
packages from these repositories. This method frees you from having to manually find and
install new applications or updates. You may use a single command to update all system
software, or search for new software by specifying criteria. </para>
<para>A network of servers provide several repositories for each version of
Fedora. The package management utilities in Fedora are already configured to use three of
these repositories: </para>
<para>Base </para>
<itemizedlist>
<listitem><para>The packages that make up a Fedora release, as it is on
disc </para></listitem>
</itemizedlist>
<para>Updates </para>
<itemizedlist>
<listitem><para>Updated versions of packages that are provided in Base
</para></listitem>
</itemizedlist>
<para>Extras </para>
<itemizedlist>
<listitem><para>Packages for a large selection of additional software
</para></listitem>
</itemizedlist>
<warning>
<title>Fedora Development Repositories</title>
<para> Fedora also includes settings for several alternative repositories.
These provide packages for various types of test system, and replace one or more of the
standard repositories. Only enable support for one of the following repositories if you
test or develop Fedora software: <code>fedora-devel</code> (Rawhide),
<code>fedora-extras-devel</code>, and
<code>updates-testing</code>. </para>
</warning>
<para>Third-party software developers also provide repositories for their
Fedora compatible packages. To learn how to configure your Fedora system to use
third-party repositories, read <xref
linkend="sn-ConfiguringRepositories"/>. </para>
<para>You may also use the <emphasis>package groups</emphasis>
provided by the Fedora repositories to manage related packages as sets. Some third-party
repositories add packages to these groups, or provide their packages as additional groups.
</para>
<important>
<title>Available Package Groups</title>
<para> To view a list of all of the available package groups for your
Fedora system, run the command <code>su -c 'yum grouplist'</code>.
</para>
</important>
<para>Use repositories to ensure that you always receive current versions of
software. If several versions of the same package are available, your management utility
automatically selects the latest version. </para>
<warning>
<title>Manually Installing Software</title>
<para> Install software using manual methods only when you are confident there
is no repository which can currently provide it. You may have to manage that software with
manual methods, instead of with Fedora software management utilities. </para>
</warning>
<para>The <code>yum</code> commands shown in this document use
repositories as package sources. Refer to <xref
linkend="sn-IsolatedInstall"/> for details of using
<code>yum</code> to install software from a package file. </para>
<para/>
</section>
<section>
<title>About Dependencies</title>
<para>Some of the files installed on a Fedora distribution are
<emphasis>libraries</emphasis> which may provide functions to multiple
applications. When an application requires a specific library, the package which contains
that library is a <emphasis>dependency</emphasis>. To properly install a
package, Fedora must first satisfy its dependencies. The dependency information for a RPM
package is stored within the RPM file. </para>
<para>The <code>yum</code> utility uses package dependency data to
ensure that all of requirements for an application are met during installation. It
automatically installs the packages for any dependencies not already present on your
system. If a new application has requirements that conflict with existing software,
<code>yum</code> aborts without making any changes to your system.
</para>
<para>
<anchor id="understanding_package_names"/>
</para>
</section>
<section>
<title>Understanding Package Names</title>
<para>Each package file has a long name that indicates several key pieces of
information. For example, this is the full name of a <code>tsclient</code>
package: </para>
<para>
<code>tsclient-0.132-6.i386.rpm</code>
</para>
<para>Management utilities commonly refer to packages with one of three formats:
</para>
<itemizedlist>
<listitem>
<para>Package name: <code>tsclient</code> </para>
</listitem>
<listitem>
<para>Package name with version and release numbers:
<code>tsclient-0.132-6</code> </para>
</listitem>
<listitem>
<para>Package name with hardware architecture:
<code>tsclient.i386</code> </para>
</listitem>
</itemizedlist>
<para>For clarity, <code>yum</code> lists packages in the format
<code>name.architecture</code>. Repositories also commonly store packages in
separate directories by architecture. In each case, the hardware architecture specified
for the package is the <emphasis>minimum</emphasis> type of machine required
to use the package. </para>
<para>i386 </para>
<itemizedlist>
<listitem><para>Suitable for any current Intel-compatible computer
</para></listitem>
</itemizedlist>
<para>noarch </para>
<itemizedlist>
<listitem><para>Compatible with all computer architectures
</para></listitem>
</itemizedlist>
<para>ppc </para>
<itemizedlist>
<listitem><para>Suitable for PowerPC systems, such as Apple Power
Macintosh </para></listitem>
</itemizedlist>
<para>x86_64 </para>
<itemizedlist>
<listitem><para>Suitable for 64-bit Intel-compatible processors, such as
Opterons </para></listitem>
</itemizedlist>
<para>Some software may be optimized for particular types of Intel-compatible
machine. Separate packages may be provided for <code>i386</code>,
<code>i586</code>, <code>i686</code> and
<code>x86_64</code> computers. A machine with at least an Intel Pentium, VIA
C3 or compatible CPU may use <code>i586</code> packages. Computers with an
Intel Pentium Pro and above, or a current model of AMD chip, may use
<code>i686</code> packages. </para>
<para>Use the short name of the package for <code>yum</code>
commands. This causes <code>yum</code> to automatically select the most recent
package in the repositories that matches the hardware architecture of your computer.
</para>
<para>Specify a package with other name formats to override the default behavior
and force <code>yum</code> to use the package that matches that version or
architecture. Only override <code>yum</code> when you know that the default
package selection has a bug or other fault that makes it unsuitable for installation.
</para>
<important>
<title>Package Names</title>
<para> You may use any of the following formats to specify a package in a
<code>yum</code> operation: <code>name, name.architecture, name-version,
name-version-release, name-version-release.architecture,</code> and
<code>epoch:name-version-release.architecture</code>. </para>
</important>
</section>
</section>
--- NEW FILE configuring-repositories.xml ---
<?xml version="1.0"?>
<section id="sn-ConfiguringRepositories">
<title>Configuring Access to Software Repositories</title>
<para>Fedora systems automatically use the Fedora Project repositories. If the
Fedora Project does not supply packages for a product, the manufacturer may provide or
recommend a separate repository. Members of the community also maintain repositories to
provide packages for Fedora systems. For example, <ulink
url="http://www.jpackage.org/">http://www.jpackage.org/</...
distributes popular Java software as packages. </para>
<para/>
<section>
<title>Adding a Repository as a Package Source</title>
<para>To add an extra repository, place a definition file in the
<code>/etc/yum.repos.d/</code> directory on your system. Package providers
make the definition files for their repositories available on their web sites.
</para>
<note>
<title>Definition File Extension</title>
<para> The names of repository definition files end with
<code>.repo</code>. </para>
</note>
<para>You must have <emphasis>root</emphasis> access to add a file
to the definitions directory. To copy the definition file
<code>example.repo</code>, type this command: </para>
<para>
<code> su -c 'cp example.repo /etc/yum.repos.d/' </code>
</para>
<para>At the prompt, enter the password for the
<emphasis>root</emphasis> account. </para>
<para>The configuration file for each repository should include a
<code>gpgkey</code> setting. This setting specifies the location of a public
key that verifies the packages provided by that repository. This public key is
automatically imported the first time that you install software from the repository. If
the configuration file provided does not include this setting, refer to <xref
linkend="sn-ManuallyAuthorizing"/>. </para>
</section>
<section id="sn-ManuallyAuthorizing">
<title>Manually Authorizing Package Sources</title>
<para>To manually add a public key to your <code>rpm</code> keyring,
use the import feature of the <code>rpm</code> utility. To import the file
<code>GPG-PUB-KEY.asc</code>, type the following command: </para>
<para>
<code> su -c 'rpm --import GPG-PUB-KEY.asc' </code>
</para>
<para>At the prompt, enter the password for the
<emphasis>root</emphasis> account. </para>
<para>You may also import public keys directly from a web site. For example, to
import the file <code>GPG-PUB-KEY.asc</code> on the web site
<emphasis>www.therepository.com</emphasis>, use this command: </para>
<para>
<code> su -c 'rpm --import
http://www.therepository.com/GPG-PUB-KEY.asc' </code>
</para>
<para>At the prompt, enter the <emphasis>root</emphasis> password.
</para>
<important>
<title>Importing the Fedora Key</title>
<para> To add the Fedora public key to the <code>rpm</code>
keyring on Fedora systems, run the command <code>su -c 'rpm --import
/usr/share/rhn/RPM-GPG-KEY-fedora'</code>. </para>
</important>
<para/>
</section>
<section>
<title>Understanding Repository Compatibility</title>
<para>The Fedora Package Collection includes several thousands of packages which
are compatible with each other. Third-party packages should be compatible with these
Fedora Project packages, unless the provider specifically states otherwise. </para>
<para>Always read the web site of the repository for information on package
compatibility before you add it as a package source. Separate repository providers may
offer different and incompatible versions of the same software. Third-party repositories
may also provide alternative packages for software that is included in Fedora
repositories. </para>
<para>Alternative packages may contain versions of the software that function
differently from the version in the Fedora Project packages. Determine the benefits and
potential incompatibilities before replacing Fedora Project packages with alternative
versions. </para>
<warning>
<title>Incompatible Repositories</title>
<para> If you configure your system to use incompatible repositories yum
operations may fail. </para>
</warning>
<para>Packages built for one version of Fedora are usually not compatible with
other versions of Fedora. The web site of the provider should specifically state which
versions of Fedora they support. </para>
<note>
<title>Old Versions of yum and Current Repositories</title>
<para>The data format for repository indexes changed with version 2.1 of
<code>yum</code>. This was the version supplied with Fedora Core 3. Repository
providers should specify the versions of Fedora that they support. To confirm that an
unlabeled repository is compatible with current versions of <code>yum</code>,
check that it has a sub-directory called <code>repodata/</code>.
</para>
</note>
<para/>
</section>
<section>
<title>Disabling or Removing Package Sources</title>
<para>Set <code>enable=0</code> in a definition file to prevent
<code>yum</code> from using that repository. The <code>yum</code>
utility ignores any definition file with this setting. </para>
<para>To completely remove access to a repository: </para>
<orderedlist numeration="arabic">
<listitem>
<para>Delete the relevant file from
<code>/etc/yum.repos.d/</code>. </para>
</listitem>
<listitem>
<para>Delete the cache directory from
<code>/var/cache/yum/</code>. </para>
</listitem>
</orderedlist>
</section>
</section>
--- NEW FILE customizing-yum.xml ---
<?xml version="1.0"?>
<section id="sn-CustomizingYum">
<title>Customizing <code>yum</code></title>
<para>To change the behavior of <code>yum</code>, you may either
edit the configuration files, or install <emphasis>plugins</emphasis>. Plugins
enable developers to add new features to <code>yum</code>. </para>
<anchor id="editing_the_yum_configuration"/>
<section>
<title>Editing the yum Configuration</title>
<para>The file <code>/etc/yum.conf</code> provides the main
configuration for <code>yum</code>. Settings in a repository definition file
override the main configuration for those operations that use the defined repository.
</para>
<para>To edit <code>/etc/yum.conf</code>, run a text editor with
<emphasis>root</emphasis> privileges. This command opens
<code>/etc/yum.conf</code> with <emphasis
role="strong">gedit</emphasis>, the default text editor for Fedora
desktop systems: </para>
<para>
<code>su -c 'gedit /etc/yum.conf'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<para>The main configuration file provides the settings that apply to all
<code>yum</code> operations. These include caching options, and proxy server
settings. The directory <code>/etc/yum.repos.d/</code> holds definition files
for each repository that <code>yum</code> uses. Plugins use the configuration
files in the directory <code>/etc/yum/pluginconf.d/</code>. </para>
<para>The following sections in this document provide further information on
configuring yum: </para>
<itemizedlist>
<listitem>
<para>
<xref linkend="sn-ConfiguringRepositories"/>
</para>
</listitem>
<listitem>
<para>
<xref linkend="sn-CustomizingYum"/>
</para>
</listitem>
<listitem>
<para>
<xref linkend="sn-YumCaching"/>
</para>
</listitem>
<listitem>
<para>
<xref linkend="sn-YumProxy"/>
</para>
</listitem>
</itemizedlist>
<note>
<title>Further Documentation</title>
<para> Refer to the <code>man</code> page for
<code>yum.conf</code> for a complete list of the configuration options
supported by <code>yum</code>. </para>
</note>
<para>
<anchor id="working_with_yum_plugins"/>
</para>
</section>
<section>
<title>Working with yum Plugins</title>
<para>Each yum plugin is a single file, written in the Python programming
language. You may download plugins from the yum project Web site, or from third-party
providers. The yum project maintains a list of plugins on the page <ulink
url="http://wiki.linux.duke.edu/YumPlugins">http://wiki.linu...;.
</para>
<note>
<title role="strong">Plugin File Extension</title>
<para> The names of <code>yum</code> plugin files end with
<code>.py</code>, the standard extension for Python scripts. </para>
</note>
<para>To install a plugin, copy it to the directory
<code>/usr/lib/yum-plugins/</code>. Create a configuration file for the plugin
in the directory <code>/etc/yum/pluginconf.d/</code>. Save the configuration
file with the same name as the plugin, but with the extension
<code>.conf</code>. </para>
<note>
<title><emphasis role="strong">root</emphasis>
Privileges Required</title>
<para> You must have <emphasis>root</emphasis> access to add files
to the directories <code>/usr/lib/yum-plugins/</code> and
<code>/etc/yum/pluginconf.d/</code>. </para>
</note>
<para>For example, to copy the plugin <code>exampleplugin.py</code>,
enter the command: </para>
<para>
<code>su -c 'cp exampleplugin.py /usr/lib/yum-plugins/'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<para>You may then create a configuration file for the plugin with a text
editor. This example uses <emphasis role="strong">gedit</emphasis>,
the default text editor for Fedora desktop systems: </para>
<para>
<code>su -c 'gedit
/etc/yum/pluginconf.d/exampleplugin.conf'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<para>Each plugin configuration file includes the enabled setting. Some plugins
also require additional settings. To determine the correct settings, either refer to the
documentation supplied with the plugin, or read the plugin file itself with any text
editor. </para>
<para/>
<screen><![CDATA[[main]
enabled=1
anotheroption=0
]]></screen>
<para>Example 3. Example Plugin Configuration File </para>
<para>
<anchor id="useful_plugins_for_fedora_users"/>
</para>
</section>
<section>
<title> Useful Plugins for Fedora Users</title>
<para>Yum is easily extensible through plugins and a number of plugins have been
written by many developers. These plugins advance the core capabilities of Yum and add
more features. This section covers the plugins that are useful to Fedora users.
</para>
<para/>
<section>
<title>Installonlyn Plugin</title>
<para>Usually software package updates work by removing the older package,
retaining the configuration and installing the newer version of a package. Kernel packages
are more unique since newer versions can be installed in parallel. Every release of Fedora
usually receives a number of kernel updates during its lifecycle due to the general policy
of staying close to upstream projects. Each of these kernel updates then occupy space and
over time will clutter the initial boot loader options. To prevent this, the installonlyn
plugin leaves "n" number of kernel packages by default removing the oldest ones
first sequentially on updates. Fedora Core 5 onwards installs this plugin by default. In
Fedora, this plugin retains the current kernel and two latest updates. You can disable
this plugin or configure it to retain a different number of kernels by setting the value
in the file /etc/yum/pluginconf.d/installonlyn.conf </para>
<para/>
</section>
<section>
<title>Fastest Mirror Plugin</title>
<para>Yum in Fedora uses a dynamic server side <ulink
url="http://fedoraproject.org/wiki/Infrastructure/MirrorManagement&q...
management infrastructure</ulink> that distributes the bandwidth consumptions on
each of these mirrors by automatically directing the update to one of the geographically
closest mirrors. This mirror is automatically checked against the master server for
consistency. </para>
<para>The fastest mirror plugin enhances the speed of updates by maintaining a
local offline hostfile cache of the speed of the mirrors. It sorts the mirror list by
speed and prioritizes the faster ones for package downloads. This plugin is not installed
by default. For installing it, use the following command or from the
<emphasis>Applications</emphasis> menu use <emphasis>Add/Remove
Software". </emphasis></para><screen><![CDATA[su -c 'yum
install yum-fastestmirror'
]]></screen><para>You can configure various settings of this plugin in the
file /etc/yum/pluginconf.d/fastestmirror.conf </para>
</section>
<section>
<title>Downloadonly Plugin</title>
<para>FIXME: Figure out how plugin works and document that. </para>
<para/>
</section>
<section>
<title>Changelog Plugin</title>
<para>When Fedora developers provide a update to a existing package, they
describe the changes in the new update in the software package change log. This plugin
helps you see the package changelog before doing a update. This plugin is not installed by
default. For installing it, use the following command or from the
Applications<emphasis> menu use </emphasis>Add/Remove
Software".</para>
<screen><![CDATA[su -c 'yum install yum-changelog'
]]></screen>
<para>Sample output: </para>
<screen><![CDATA[su -c 'yum update frysk --changelog'
Loading "changelog" plugin
Setting up Update Process
Setting up repositories
Reading repository metadata in from local files
Resolving Dependencies
--> Populating transaction set with selected packages. Please wait.
---> Package frysk.i686 0:0.0.1.2006.12.01.rh1-1.fc6 set to be updated
--> Running transaction check
Changes in packages about to be updated:
frysk - 0.0.1.2006.12.01.rh1-1.fc6.i686
* Sat Dec 2 03:30:00 2006 Stepan Kasal <skasal(a)redhat.com> -
0.0.1.2006.12.01.rh1-1
- New upstream version.
- Resolves: #211288.
* Fri Dec 1 03:30:00 2006 Stepan Kasal <skasal(a)redhat.com> -
0.0.1.2006.11.30.rh1-1
- New upstream version.
- The stamp file for glade files has been renamed.
Dependencies Resolved
=============================================================================
Package Arch Version Repository Size
=============================================================================
Updating:
frysk i686 0.0.1.2006.12.01.rh1-1.fc6 updates 7.5 M
Transaction Summary
=============================================================================
Install 0 Package(s)
Update 1 Package(s)
Remove 0 Package(s)
Total download size: 7.5 M
Is this ok [y/N]:
]]></screen>
<para>By default, the package changelog is showed before doing an update. If you
prefer to see the changelog after doing an update instead, you can change the setting from
when=pre to when=post in the file /etc/yum/pluginconf.d/changelog.conf. A sample output
after the configuration has been changed from 'pre' to 'post'
</para>
<para/>
<screen><![CDATA[su -c 'yum update frysk --changelog'
Loading "changelog" plugin
Setting up Update Process
Setting up repositories
Reading repository metadata in from local files
Resolving Dependencies
--> Populating transaction set with selected packages. Please wait.
---> Package frysk.i686 0:0.0.1.2006.12.01.rh1-1.fc6 set to be updated
--> Running transaction check
Dependencies Resolved
=============================================================================
Package Arch Version Repository Size
=============================================================================
Updating:
frysk i686 0.0.1.2006.12.01.rh1-1.fc6 updates 7.5 M
Transaction Summary
=============================================================================
Install 0 Package(s)
Update 1 Package(s)
Remove 0 Package(s)
Total download size: 7.5 M
Is this ok [y/N]: y
Downloading Packages:
(1/1): frysk-0.0.1.2006.1 100% |=========================| 7.5 MB 04:24
Running Transaction Test
Finished Transaction Test
Transaction Test Succeeded
Running Transaction
Updating : frysk ######################### [1/2]
Cleanup : frysk ######################### [2/2]
Changes in updated packages:
frysk - 0.0.1.2006.12.01.rh1-1.fc6.i686
* Sat Dec 2 03:30:00 2006 Stepan Kasal <skasal(a)redhat.com> -
0.0.1.2006.12.01.rh1-1
- New upstream version.
- Resolves: #211288.
* Fri Dec 1 03:30:00 2006 Stepan Kasal <skasal(a)redhat.com> -
0.0.1.2006.11.30.rh1-1
- New upstream version.
- The stamp file for glade files has been renamed.
Updated: frysk.i686 0:0.0.1.2006.12.01.rh1-1.fc6
Complete!
]]></screen>
</section>
<section>
<title>Skip-broken Plugin</title>
<para>Yum by default checks to make all dependencies are resolved before doing a
update, however on occasions like when testing the Fedora development tree or when there
is a known dependency issue in the software repository it is useful to skip the broken
dependencies automatically instead of having to manually specify the exact packages to
ignore in the command line or yum configuration file. The skip-broken plugin helps do
that. This plugin is not installed by default. For installing it, use the following
command or from the <emphasis>Applications</emphasis> menu use
<emphasis>Add/Remove Software".
</emphasis></para><screen><![CDATA[su -c 'yum install
yum-skip-broken'
]]></screen><para>You can use this plugin doing a update by specifying the
following command line argument. </para><screen><![CDATA[su -c 'yum
update --skip-broken'
]]></screen><para>You can disable this plugin by changing the option in the
file /etc/yum/pluginconf.d/skip-broken.conf </para>
</section>
<section><title>Allowdowngrade Plugin</title><para>The core Yum
package manager does not have the functionality to let users downgrade a package. This is
a design choice to favor robustness over the additional functionality. Unlike package
updates, downgrades are not tested usually and hence may not have the desired effect.
However advanced users would still find this feature useful to recover out of a broken
update. This plugin adds the ability to perform downgrades of packages in Fedora. This
plugin is not installed by default. For installing it, use the following command or from
the <emphasis>Applications</emphasis> menu use <emphasis>Add/Remove
Software</emphasis>.</para>
<screen><![CDATA[su -c 'yum install yum-allowdowngrade'
]]></screen>
<para>You can use this plugin doing a update by specifying the following command
line argument. </para>
<screen><![CDATA[su -c 'yum update -allow-downgrade'
]]></screen>
<para>You can disable this plugin by changing the option in the file
/etc/yum/pluginconf.d/allowdowngrade.conf </para>
</section>
<section>
<title>Disabling All Plugins</title>
<para>If you would like to disable all the plugins while running Yum, you can
use the following command line argument </para>
<para/>
<screen><![CDATA[su -c 'yum update --noplugins'
]]></screen>
<para/>
</section>
<section>
<title>Developing New Plugins</title>
<para>If you are interested in developing your own plugins to add new features
or change the behavior of Yum, refer to the guidelines at <ulink
url="http://wiki.linux.duke.edu/WritingYumPlugins">http://wi...;.
Join the yum development list at <ulink
url="https://lists.dulug.duke.edu/mailman/listinfo/yum-devel"&g...
to collaborate with Yum developers. </para>
</section>
</section>
</section>
--- NEW FILE introduction.xml ---
<?xml version="1.0"?>
<section id="sn-Introduction">
<title>Introduction</title>
<section>
<title>About this Document</title>
<para><emphasis>Purpose</emphasis>: How to install and update
software packages from the desktop and the CLI. </para>
<para><emphasis>Audience</emphasis>: Individuals who are unfamiliar
with software package management in Fedora. </para>
<para><emphasis>Approach</emphasis>: Explain basic principles;
explain one principle at a time; do not assume familiarity with any Linux/UNIX-specific
terminology or concepts; compare functionality where appropriate to what the reader may
know from other operating systems, particularly Microsoft Windows. </para>
<para><emphasis>Assumptions:</emphasis> The reader has a default
installation of Fedora which includes the desktop components. The reader has a user
account with the default settings. The reader <emphasis
role="strong">does</emphasis> have access to the
<emphasis>root</emphasis> password. The user does not have a degree in
Computer Science. </para>
</section>
<section>
<title>Using This Document</title>
<para>This document is a reference for managing software with Fedora. You may
wish to read some or all of the sections, depending upon your needs and level of
experience. If you are a new user, start with: </para>
<itemizedlist>
<listitem>
<para>
<xref linkend="sn-Concepts"/>
</para>
</listitem>
<listitem>
<para>
<xref linkend="sn-Pirut"/>
</para>
</listitem>
<listitem>
<para>
<xref linkend="sn-Pup"/>
</para>
</listitem>
</itemizedlist>
<para>These guides explain basic concepts of software management in Fedora,
and introduce the various graphical interfaces for yum. Experienced Linux users should
start with <xref linkend="sn-ManageWithYum"/>.</para>
<tip>
<title>Previous Versions of Fedora</title>
<para> This document describes the configuration of <code>yum</code>
on current versions of Fedora. You must perform the additional step noted in <xref
linkend="sn-ManuallyAuthorizing"/> to enable <code>yum</code> on
earlier versions Fedora. </para>
</tip>
<warning>
<title>Warning: Avoid Logging in with the Root Account</title>
<para> You do not need to log in with the <code>root</code> account
in order to manage your Fedora system. All of the commands shown in this tutorial that
require <code>root</code> access will prompt you for the
<code>root</code> password. The example terminal commands use <code>su
-c</code> to provide this facility. Graphical applications that require root access
will automatically prompt for the root password when launched. </para>
</warning>
<para>Most of the examples in this document use the package
<code>tsclient</code>, which is included with Fedora. The
<code>tsclient</code> package provides an application for remote desktop
access. The example commands for Fedora package groups use the <code>MySQL
Database</code> group. To use the examples, substitute the name of the relevant
package for <code>tsclient</code>. </para>
<para>Fedora includes a <code>yum</code> configuration that is
suitable for independent systems with Internet access. You may use
<code>yum</code> and related software on such systems without any additional
configuration. </para>
<para>If your system is part of a managed network, consult your network
administrators for advice. You may need to configure <code>yum</code> to use a
network proxy server.
<xref linkend="sn-YumProxy"/> explains how to configure
<code>yum</code> to use a proxy server. Administrators may also suggest or
require that <code>yum</code> clients use specific package repositories. Refer
to <xref linkend="sn-ConfiguringRepositories"/> for instructions on how to
configure access to repositories. </para>
<para>To improve performance and enable disconnected operations, activate the
<code>yum</code> caches on your system. Refer to <xref
linkend="sn-YumCaching"/> for more information on the caching option.
</para>
<para/>
</section>
<section>
<title>Additional Resources</title>
<para>The <code>yum</code> utility has features and options not
discussed in this document. Read the <code>man</code> pages for
<code>yum(8)</code> and <code>yum.conf(5)</code> to learn more,
using the following commands: </para>
<para>
<code>man yum</code>
</para>
<para>
<code>man yum.conf</code>
</para>
<para>Other useful <code>yum</code> resources on the Internet
include: </para>
<para>Project Web site </para>
<itemizedlist>
<listitem>
<para>
<ulink
url="http://linux.duke.edu/projects/yum/">http://linux.duke....
</para>
</listitem>
</itemizedlist>
<para>Users mailing list </para>
<itemizedlist>
<listitem>
<para>
<ulink
url="https://lists.dulug.duke.edu/mailman/listinfo/yum/">htt...
</para>
</listitem>
</itemizedlist>
<para>Development mailing list </para>
<itemizedlist>
<listitem>
<para>
<ulink
url="https://lists.dulug.duke.edu/mailman/listinfo/yum-devel/"&...
</para>
</listitem>
</itemizedlist>
<important>
<title>Note: Check Bugzilla First</title>
<para> If you encounter a persistent error with a specific operation, visit
<ulink
url="https://bugzilla.redhat.com">https://bugzilla.redhat.com</ulink>
and review the bug reports for the package or packages involved. An error in a package may
cause all <code>yum</code> operations that rely on that package to fail.
Please file bug reports for Fedora packages, including <code>yum</code>, on
this Bugzilla web site. </para>
</important>
</section>
</section>
--- NEW FILE isolated-install.xml ---
<?xml version="1.0"?>
<section id="sn-IsolatedInstall">
<title>Installing Software from an Isolated Package</title>
<para>Use repositories and the standard <code>yum</code> commands to
locate and install new software, unless the software package is not available from any
repository. In these cases, use the <code>localinstall</code> function to
install the software from the package file. </para>
<important>
<title>Public Key is Required</title>
<para> Ensure that the public key for the package source has been imported
before you install a package without a repository. Refer to <xref
linkend="sn-ManuallyAuthorizing"/>. </para>
</important>
<para>Enter this command to install the package
<code>tsclient-0.132-4.i386.rpm</code>: </para>
<para>
<code>su -c 'yum localinstall tsclient-0.132-4.i386.rpm'</code>
</para>
<para>At the prompt, enter the <emphasis>root</emphasis> password.
</para>
<note>
<title>Previously Installed Software is Updated</title>
<para> If the package provides a later version of software that is already
installed on your system, <code>yum</code> updates the installed software.
</para>
</note>
<para>If the package requires software that is not installed on your system,
<code>yum</code> attempts to meet the dependencies with packages from the
configured repositories. You may need to manually download and install additional packages
in order to satisfy all of the dependencies. </para>
<warning>
<title>Maintaining Manually Installed Software</title>
<para> If you install software that is not provided by a repository,
<code>yum update</code> cannot automatically upgrade it as new versions become
available. To ensure that you have the latest packages, subscribe to e-mail or RSS
services that notify you when new versions are released. </para>
</warning>
</section>
--- NEW FILE manage-with-yum.xml ---
<?xml version="1.0"?>
<section id="sn-ManageWithYum">
<title>Managing Software with yum</title>
<para>Use the <code>yum</code> utility to modify the software on
your system in four ways: </para>
<itemizedlist>
<listitem><para>install new software from package repositories
</para></listitem>
<listitem><para>install new software from an individual package file
</para></listitem>
<listitem><para>update existing software on your system
</para></listitem>
<listitem><para>remove unwanted software from your system
</para></listitem>
</itemizedlist>
<note>
<title>Installing Software from a Package File</title>
<para> The <code>yum</code> commands shown in this section use
repositories as package sources. Refer to <xref
linkend="sn-IsolatedInstall"/> for details of using
<code>yum</code> to install software from an individual package file.
</para>
</note>
<para>To use <code>yum</code>, specify a function and one or more
packages or package groups. Each section below gives some examples. </para>
<para>For each operation, <code>yum</code> downloads the latest
package information from the configured repositories. If your system uses a slow network
connection yum may require several seconds to download the repository indexes and the
header files for each package. </para>
<para>The <code>yum</code> utility searches these data files to
determine the best set of actions to produce the required result, and displays the
transaction for you to approve. The transaction may include the installation, update, or
removal of additional packages, in order to resolve software dependencies. </para>
<para>This is an example of the transaction for installing
<code>tsclient</code>: </para>
<para/>
<screen><![CDATA[=============================================================================
Package Arch Version Repository Size
=============================================================================
Installing:
tsclient i386 0.132-6 base 247 k
Installing for dependencies:
rdesktop i386 1.4.0-2 base 107 k
Transaction Summary
=============================================================================
Install 2 Package(s)
Update 0 Package(s)
Remove 0 Package(s)
Total download size: 355 k
Is this ok [y/N]:]]></screen>
<para>Example 1. Format of <code>yum</code> Transaction Reports
</para>
<para>Review the list of changes, and then press <emphasis
role="strong">[y]</emphasis> to accept and begin the process. If you
press <emphasis role="strong">[N]</emphasis> or <emphasis
role="strong">[Enter]</emphasis>, <code>yum</code> does not
download or change any packages. </para>
<note>
<title>Package Versions</title>
<para> The <code>yum</code> utility only displays and uses the
newest version of each package, unless you specify an older version. </para>
</note>
<para>The <code>yum</code> utility also imports the repository
public key if it is not already installed on the rpm keyring. </para>
<para>This is an example of the public key import: </para>
<para/>
<screen><![CDATA[warning: rpmts_HdrFromFdno: Header V3 DSA signature: NOKEY,
key ID 4f2a6fd2
public key not available for tsclient-0.132-6.i386.rpm
Retrieving GPG key from file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora
Importing GPG key 0x4F2A6FD2 "Fedora Project <fedora(a)redhat.com>"
Is this ok [y/N]:]]></screen>
<para>Example 2. Format of <code>yum</code> Public Key Import
</para>
<para>Check the public key, and then press <emphasis
role="strong">[y]</emphasis> to import the key and authorize the key
for use. If you press <emphasis role="strong">[N]</emphasis> or
<emphasis role="strong">[Enter]</emphasis>,
<code>yum</code> stops without installing any packages. </para>
<para>To ensure that downloaded packages are genuine,
<code>yum</code> verifies the digital signature of each package against the
public key of the provider. Once all of the packages required for the transaction are
successfully downloaded and verified, <code>yum</code> applies them to your
system. </para>
<note>
<title>Transaction Log</title>
<para> Every completed transaction records the affected packages in the log
file <code>/var/log/yum.log</code>. You may only read this file with
<emphasis>root</emphasis> access. </para>
</note>
<para/>
<section>
<title>Installing New Software with yum</title>
<para>To install the package <code>tsclient</code>, enter the
command: </para>
<para>
<code>su -c 'yum install tsclient'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<para>To install the package group <code>MySQL Database</code>,
enter the command: </para>
<para>
<code>su -c 'yum groupinstall "MySQL
Database"'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<important>
<title>New Services Require Activation</title>
<para> When you install a service, Fedora does not activate or start it. To
configure a new service to run on bootup, choose <emphasis>System →
Administration → Services</emphasis> from the top desktop panel, or use
the <code>chkconfig</code> and <code>service</code> command-line
utilities. </para>
</important>
<anchor id="updating_software"/>
</section>
<section>
<title>Updating Software with yum</title>
<para>To update the <code>tsclient package</code> to the latest
version, type: </para>
<para>
<code>su -c 'yum update tsclient'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<important>
<title>New Software Versions Require Reloading</title>
<para> If a piece of software is in use when you update it, the old version
remains active until the application or service is restarted. Kernel updates take effect
when you reboot the system. </para>
</important>
<note>
<title>Kernel Packages</title>
<para> Kernel packages remain on the system after they have been superseded by
newer versions. This enables you to boot your system with an older kernel if an error
occurs with the current kernel. To minimize maintenance, yum automatically removes
obsolete kernel packages from your system, retaining only the current kernel and the
previous version. </para>
</note>
<para>To update all of the packages in the package group <code>MySQL
Database</code>, enter the command: </para>
<para>
<code>su -c 'yum groupupdate "MySQL Database"'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<note>
<title>Updating the Entire System</title>
<para> To update all of the packages on your Fedora system, use the commands
described in <xref linkend="sn-UpdateWithYum"/>. </para>
</note>
<para/>
</section>
<section>
<title>Removing Software with yum</title>
<para>To remove software, <code>yum</code> examines your system for
both the specified software, and any software which claims it as a dependency. The
transaction to remove the software deletes both the software and the dependencies.
</para>
<para>To remove the <code>tsclient</code> package from your system,
use the command: </para>
<para>
<code>su -c 'yum remove tsclient'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<para>To remove all of the packages in the package group <code>MySQL
Database</code>, enter the command: </para>
<para>
<code>su -c 'yum groupremove "MySQL Database"'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<note>
<title>Data and Configuration File Retention</title>
<para> The removal process leaves user data in place but may remove
configuration files in some cases. If a package removal does not include the configuration
file, and you reinstall the package later, it may reuse the old configuration file.
</para>
</note>
</section>
</section>
--- NEW FILE pirut.xml ---
<?xml version="1.0"?>
<section id="sn-Pirut">
<title>Managing Software with Pirut</title>
<para>This section explains <emphasis
role="strong">Pirut</emphasis>, Fedora's graphical package
management program. It demonstrates the different search facilities within <emphasis
role="strong">Pirut</emphasis> and how to install a package. The
<emphasis role="strong">Banshee</emphasis> music management package
is used as an example. </para>
<para/>
<section>
<title>Browse Software</title>
<para>Start <emphasis role="strong">Pirut</emphasis> by
selecting the <emphasis>Add/Remove Programs</emphasis> entry in the
<emphasis>Applications</emphasis> menu, entering your
<code>root</code> password when prompted. </para>
<para>The program starts in <emphasis>Browse</emphasis> view by
default. This view organizes packages into related groups, displaying top level groups on
the left and sub-categories on the right. When a tick is present next to a sub-category,
it indicates applications from that group are installed. </para>
<para>To install <emphasis
role="strong">Banshee</emphasis>, select the <emphasis>Sound and
Video</emphasis> sub-category and press the <emphasis>Optional
Packages</emphasis> button. Locate <emphasis
role="strong">Banshee</emphasis> in the list and queue it for
installation by ticking its box with a left-click. As many packages as desired can be
queued for installation by ticking the appropriate boxes. </para>
<para>To add packages from other groups or sub-categories to the queue, browse
to the desired group or sub-category and proceed as before. The <emphasis>Optional
Packages</emphasis> button is only available when the desired sub-category is
ticked. Ticking a previously un-ticked sub-category automatically queues for installation
any packages required for that sub-category. </para>
<para>To install the queued packages press the
<emphasis>Apply</emphasis> button. </para>
<note>
<title>Removing packages</title>
<para> Remove packages by un-ticking the appropriate boxes and pressing the
<emphasis>Apply</emphasis> button. </para>
</note>
</section>
<section>
<title>Dependencies</title>
<para>After applying changes, <emphasis
role="strong">Pirut</emphasis> prompts to confirm the packages you have
selected. Proceed if the list is correct, otherwise cancel and refine the selection.
</para>
<note>
<title>Dependencies</title>
<para> Dependenices are packages that are required by another package to
function correctly. </para>
</note>
<para><emphasis role="strong">Pirut</emphasis> now
resolves any dependencies. A dialog informs you which dependencies have been found, and
are automatically marked for installation. Confirm this list to proceed. </para>
<warning>
<title>Dependencies can be removed</title>
<para> When a package is removed it is possible other packages may
have relied on it to function correctly. If this is the case <emphasis
role="strong">Pirut</emphasis> also removes these other applications.
Check the dependency dialog and cancel if any of the packages marked for removal are still
needed. This can be corrected by refining your package selection. </para>
</warning>
</section>
<section>
<title>Search Software</title>
<para>When the desired application's name is known, the
<emphasis>Search</emphasis> tab is more efficient. </para>
<para>Select the <emphasis>Search</emphasis> tab from the top of the
window and enter <emphasis role="strong">Banshee</emphasis> into the
search box. Press enter to begin the search. Results, including related packages, are
shown in the box below. To find more information about a package before installation,
highlight it with a left-click and press the <emphasis>Package
Details</emphasis> text below. </para>
<para>To queue a package for installation or removal, toggle its box as
appropriate. Once all the packages have been selected press
<emphasis>Apply</emphasis>. </para>
<para/>
</section>
<section>
<title>List Software</title>
<para>The list tab displays all available packages. Packages can be queued for
installation or removal in the same manner as before. Once satisfied with the selections,
press the <emphasis>Apply</emphasis> button to commit the changes.
</para>
</section>
</section>
--- NEW FILE pup.xml ---
<?xml version="1.0"?>
<section id="sn-Pup">
<title>Updating Software With Pup</title>
<para>This chapter explains how to use the <emphasis
role="strong">Pup</emphasis> graphical update program, and how
<emphasis role="strong">Puplet</emphasis> works to provide
notifications of available updates. </para>
<para/>
<section>
<title>Update Notifications</title>
<para><emphasis role="strong">Puplet</emphasis> works
constantly in the background, checking for available software updates from the enabled
repositories. When updates become available a package icon appears in the notification
area, along with an alert which appears for a short time and reveals the number of updates
available. </para>
<para>Once the notification tray icon is present, there are a number of
possible actions it can perform: </para>
<itemizedlist>
<listitem>
<para><emphasis>Refresh</emphasis> will check for new updates
</para>
</listitem>
<listitem>
<para><emphasis>View Updates</emphasis> launches <emphasis
role="strong">Pup</emphasis> and allows you to find more details about
the packages to be updated, to de-select some updates, and to start the update process
</para>
</listitem>
<listitem>
<para>
<emphasis>Apply Updates</emphasis>
</para>
</listitem>
<listitem>
<para><emphasis>Quit</emphasis> closes <emphasis
role="strong">Puplet</emphasis> until the next time the system starts
</para>
</listitem>
</itemizedlist>
<para/>
</section>
<section>
<title>The Package Updater</title>
<para>This program features a scrollable text window under the heading
<emphasis>Updates available</emphasis>. In this text window all of the
available updates are listed, and all are selected by default. If you want to remove any
of the packages queued for update, left click the ticked box next to the relevant package.
</para>
<para>Some updates have a circular arrow icon next to them, indicating that
these changes won't be applied until the next system reboot. </para>
<para>Further information about the updates can be found by selecting the
desired package, then left clicking the <emphasis>Update Details</emphasis>
text. </para>
<para>Once satisfied with the package selection left click the
<emphasis>Apply Updates</emphasis> button. Pup checks for dependencies,
ensuring that the updated packages will have everything required to function correctly. If
dependencies are added a dialogue will be displayed informing you which new packages are
set to be installed. Review this dialog and click
<emphasis>Continue</emphasis> if it is OK. </para>
<para>The packages will then be downloaded and installed. If a reboot is
needed for some of the changes to take place, you will be informed of this at the end of
the updates. </para>
</section>
</section>
--- NEW FILE search-with-yum.xml ---
<?xml version="1.0"?>
<section>
<title>Searching for Packages with <code>yum</code></title>
<para/>
<section>
<title>Searching for Packages with yum</title>
<para>Use the search features of <code>yum</code> to find software
that is available from the configured repositories, or already installed on your system.
Searches automatically include both installed and available packages. </para>
<para>The format of the results depends upon the option. If the query produces
no information, there are no packages matching the criteria. </para>
<para/>
</section>
<section>
<title>Searching by Package Name and Attributes</title>
<para>To search for a specific package by name, use the list function. To search
for the package <code>tsclient</code>, use the command: </para>
<para>
<code>su -c 'yum list tsclient'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<para>To make your queries more precise, specify packages with a name that
include other attributes, such as version or hardware architecture. To search for version
0.132 of the application, use the command: </para>
<para>
<code>su -c 'yum list tsclient-0.132'</code>
</para>
<note>
<title>Valid Package Attributes</title>
<para> Refer to <xref linkend="sn-Concepts"/> for information
on package name formats and the attributes that they include. </para>
</note>
<para/>
</section>
<section>
<title>Advanced Searches</title>
<para>If you do not know the name of the package, use the search or provides
options. Alternatively, use wild cards with any <code>yum</code> search option
to broaden the search criteria. </para>
<para>The search option checks the names, descriptions, summaries and listed
package maintainers of all of the available packages to find those that match. For
example, to search for all packages that relate to Palm Pilots, type: </para>
<para>
<code>su -c 'yum search PalmPilot'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<para>The provides function checks both the files included in the packages and
the functions that the software provides. This option requires
<code>yum</code> to download and read much larger index files than with the
search option. </para>
<para>To search for all packages that include files called
<code>libneon</code>, type: </para>
<para>
<code>su -c 'yum provides libneon'</code>
</para>
<para>To search for all packages that either provide a MTA (Mail Transport
Agent) service, or include files with <code>mta</code> in their name:
</para>
<para>
<code>su -c 'yum provides MTA'</code>
</para>
<para>For each command, at the prompt enter the password for the
<emphasis>root</emphasis> account. </para>
<para>Use the standard wild-card characters to run any search option with a
partial word or name: <code>?</code> to represent any one character, and
<code>*</code> to mean zero or more characters. Always add the escape
character <code>\</code> before wild-cards. </para>
<para>To list all packages with names that begin with
<code>tsc</code>, type: </para>
<para>
<code>su -c 'yum list tsc\*'</code>
</para>
<para/>
</section>
<section>
<title>Understanding Matches</title>
<para>Searches with <code>yum</code> show all of the packages that
match your criteria. Packages must meet the terms of the search exactly to be considered
matches, unless you use wild-cards. </para>
<para>For example, a search query for <code>shadowutils</code> or
<code>shadow-util</code> would not produce the package
<code>shadow-utils</code>. This package would match and be shown if the query
was <code>shadow-util\?</code>, or <code>shadow\*</code>.
</para>
</section>
</section>
--- NEW FILE tools.xml ---
<?xml version="1.0"?>
<section>
<title>Software Management Tools in Fedora</title>
<para>The <code>yum</code> command-line utility is a complete
software management system. Fedora also includes two graphical applications for software
management that use <code>yum</code>. The <emphasis
role="strong">pup</emphasis> utility provides an interface for updating
software, and the <emphasis role="strong">pirut</emphasis>
application enables you to add or remove software. </para>
<para>Both graphical tools appear in the
<emphasis>Applications</emphasis> desktop menu. To update your system with
<emphasis role="strong">pup</emphasis>, select
<emphasis>Applications → System Tools → Software
Updater</emphasis>. To add or remove software with <emphasis
role="strong">pirut</emphasis>, select <emphasis>Applications
→ Add/Remove Software</emphasis>. </para>
<warning>
<title>Root Access Needed</title>
<para> When using <emphasis role="strong">pup</emphasis>
or <emphasis role="strong">pirut</emphasis> you will be asked for
the root password when starting these programs. </para>
</warning>
<para>There is also <emphasis
role="strong">puplet</emphasis> which automatically checks for, and
alerts you to, updates for your system. It appears as an icon in the notification area
when new updates are available. Click this icon to launch <emphasis
role="strong">pup</emphasis> and update your system. </para>
<para>The <code>rpm</code> command-line utility has many functions
for working with individual RPM packages. You may use it to manually install and remove
packages from your system. If you install software with the <code>rpm</code>
utility, you must manually check and install any dependencies. For this reason,
<emphasis role="strong">pirut</emphasis> and
<code>yum</code> are the recommended methods for installing software.
</para>
<warning>
<title>Current Package Versions</title>
<para> The <emphasis role="strong">pirut</emphasis> and
<code>yum</code> utilities ensure that you have the most recent version of
software packages. Other methods do not guarantee that the packages are current.
</para>
</warning>
</section>
--- NEW FILE update-with-yum.xml ---
<?xml version="1.0"?>
<section id="sn-UpdateWithYum">
<title>Updating Your System with <code>yum</code></title>
<para>Use the update option to upgrade all of your Fedora system software to the
latest version with one operation. </para>
<para>To perform a full system update, type this command: </para>
<para>
<code>su -c 'yum update'</code>
</para>
<para>At the prompt, enter the <emphasis>root</emphasis> password.
</para>
<para/>
<section>
<title>Automatically Updating Your System</title>
<para>The <code>yum</code> package supplied with Fedora includes
scripts to perform full system updates every day. To activate automatic daily updates,
enter this command: </para>
<para>
<code>su -c '/sbin/chkconfig --level 345 yum-updatesd on; /sbin/service
yum-updatesd start'</code>
</para>
<para>At the prompt, enter the password for the
<emphasis>root</emphasis> account. </para>
</section>
</section>
--- NEW FILE yum-caching.xml ---
<?xml version="1.0"?>
<section id="sn-YumCaching">
<title>Working with yum Caching</title>
<para>By default, current versions of <code>yum</code> delete the
data files and packages that they download, after these have been successfully used for an
operation. This minimizes the amount of storage space that <code>yum</code>
uses. You may enable caching, so that <code>yum</code> retains the files that
it downloads in cache directories. </para>
<para>Caches provide three advantages: </para>
<itemizedlist>
<listitem>
<para>The performance of <code>yum</code> increases
</para>
</listitem>
<listitem>
<para>You may carry out <code>yum</code> operations without a
network connection, by using only the caches </para>
</listitem>
<listitem><para>You may copy packages from the caches and reuse them
elsewhere </para></listitem>
</itemizedlist>
<para>By default, <code>yum</code> stores temporary files under the
directory <code>/var/cache/yum/</code>, with one subdirectory for each
configured repository. The <code>packages/</code> directory within each
repository directory holds the cached packages. For example, the directory
<code>/var/cache/yum/development/packages/</code> holds packages downloaded
from the development repository. </para>
<note>
<title role="strong">Clearing the <code>yum</code>
Caches</title>
<para> Cached files use disk space until removed. You may wish to periodically
clear the <code>yum</code> caches to recover capacity. Refer to <xref
linkend="sn-YumCaching"/> for information on clearing the caches.
</para>
</note>
<para>If you remove a package from the cache, you do not affect the copy of the
software installed on your system. </para>
<section>
<title>Enabling the Caches</title>
<para>To configure <code>yum</code> to retain downloaded files
rather than discarding them, set the <code>keepcache</code> option in
<code>/etc/yum.conf</code> to <code>1</code>: </para>
<para>
<code>keepcache=1</code>
</para>
<para>Refer to <xref linkend="sn-CustomizingYum"/> for more
information on editing the <code>yum</code> configuration file. </para>
<para>Once you enable caching, every <code>yum</code> operation may
download package data from the configured repositories. To ensure that the caches have a
set of package data, carry out an operation after you enable caching. Use a list or search
query to download package data without modifying your system. </para>
<para/>
</section>
<section>
<title>Using yum in Cache-only Mode</title>
<para>To carry out a <code>yum</code> command without a network
connection, add the <code>-C</code> option. This causes
<code>yum</code> to proceed without checking any network repositories, and use
only cached files. In this mode, yum may only install packages that have been downloaded
and cached by a previous operation. </para>
<para>To search for the package <code>tsclient</code> without using
a network connection, enter the command: </para>
<para>
<code>su -c 'yum -C list tsclient'</code>
</para>
<para>Enter the password for the <emphasis>root</emphasis> account
when prompted. </para>
<note>
<title>Cache-only Mode Requires Cached Data</title>
<para> Cache-only mode requires package data to exist in the caches. If you
enable caching, every <code>yum</code> operation may update the data files,
unless cache-only mode is specified for the operation. </para>
</note>
<anchor id="clearing_the_yum_caches"/>
</section>
<section>
<title>Clearing the yum Caches</title>
<para>If you configure it to do so, <code>yum</code> retains the
packages and package data files that it downloads, so that they may be reused in future
operations without being downloaded again. To purge the package data files, use this
command: </para>
<para>
<code>su -c 'yum clean headers'</code>
</para>
<para>Run this command to remove all of the packages held in the caches:
</para>
<para>
<code>su -c 'yum clean packages'</code>
</para>
<para>When using these commands, at the prompt, enter the password for the
<emphasis>root</emphasis> account. </para>
<para>Purging cached files causes those files to downloaded again the next time
that they are required. This increases the amount of time required to complete the
operation. </para>
</section>
</section>
--- NEW FILE yum-proxy.xml ---
<?xml version="1.0"?>
<section id="sn-YumProxy">
<title>Using yum with a Proxy Server</title>
<para>By default, <code>yum</code> accesses network repositories
with HTTP. All <code>yum</code> HTTP operations use HTTP/1.1, and are
compatible with web proxy servers that support this standard. You may also access FTP
repositories, and configure <code>yum</code> to use an FTP proxy server. The
<code>squid</code> package provides a proxy service for both HTTP/1.1 and FTP
connections. </para>
<note>
<title>Modifying <code>yum</code> for Network
Compatibility</title>
<para> Refer to the <code>man</code> page for
<code>yum.conf</code> for information on HTTP settings that may be modified
for compatibility with nonstandard web proxy servers. Alternatively, configure
<code>yum</code> to use an FTP proxy server, and access repositories that
support FTP. The Fedora repositories support both HTTP and FTP. </para>
</note>
<section>
<title>Configuring Proxy Server Access</title>
<para>To enable all <code>yum</code> operations to use a proxy
server, specify the proxy server details in <code>/etc/yum.conf</code>. The
proxy setting must specify the proxy server as a complete URL, including the TCP port
number. If your proxy server requires a username and password, specify these by adding
<code>proxy_username</code> and <code>proxy_password</code>
settings. </para>
<para>The settings below enable yum to use the proxy server
<code>mycache.mydomain.com</code>, connecting to port 3128, with the username
<code>yum-user</code> and the password <code>qwerty</code>.
</para>
<para/>
<screen><![CDATA[# The proxy server - proxy server:port number
proxy=http://mycache.mydomain.com:3128
# The account details for yum connections
proxy_username=yum-user
proxy_password=qwerty
]]></screen>
<para>Example 4. Configuration File Settings for Using A Proxy Server
</para>
<note>
<para>Older versions of yum may require a "/" after the port number:
<code> proxy=http://mycache.mydomain.com:3128/</code> </para>
</note>
<note>
<title>Global Settings</title>
<para> If you define a proxy server in <code>/etc/yum.conf</code>,
all users connect to the proxy server with those details when using
<code>yum</code>. </para>
</note>
<para/>
</section>
<section>
<title>Configuring Proxy Server Access for a Single User</title>
<para>To enable proxy access for a specific user, add the lines in the example
box below to the user's shell profile. For the default <code>bash
shell</code>, the profile is the file <code>~/.bash_profile</code>. The
settings below enable <code>yum</code> to use the proxy server
<code>mycache.mydomain.com</code>, connecting to port 3128. </para>
<para/>
<screen><![CDATA[# The Web proxy server used by this account
http_proxy="http://mycache.mydomain.com:3128"
export http_proxy
]]></screen>
<para>Example 5. Profile Settings for Using a Proxy Server </para>
<para>If the proxy server requires a username and password, add these to the
URL. To include the username <code>yum-user</code> and the password
<code>qwerty</code>, add these settings: </para>
<para/>
<screen><![CDATA[# The Web proxy server, with the username and password for
this account
http_proxy="http://yum-user:qwerty@mycache.mydomain.com:3128"
export http_proxy ]]></screen>
<para>Example 6. Profile Settings for a Secured Proxy Server </para>
<note>
<title>The <code>http_proxy</code> Environment
Variable</title>
<para> The <code>http_proxy</code> environment variable is also
used by <code>curl</code> and other utilities. Although
<code>yum</code> itself may use <code>http_proxy</code> in either
upper-case or lower-case, <code>curl</code> requires the name of the variable
to be in lower-case. </para>
</note>
</section>
</section>
View full diff with command:
/usr/bin/cvs -f diff -kk -u -N -r 1.7 -r 1.8 yum-software-management.xml
Index: yum-software-management.xml
===================================================================
RCS file: /cvs/docs/yum-software-management/en_US/yum-software-management.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- yum-software-management.xml 6 Aug 2007 04:39:27 -0000 1.7
+++ yum-software-management.xml 21 Jan 2008 22:21:19 -0000 1.8
@@ -1,2444 +1,31 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-
-<!-- Group: Automatic Entities -->
-
- <!-- Local entities for Yum Tutorial -->
-
- <!-- Group: Document revision markings -->
-
- <!ENTITY DOCNAME "yum-software-management" > <!-- Document name
-->
- <!ENTITY DOCVERSION "1.31" > <!-- Version number -->
- <!ENTITY DOCDATE "2006-04-30" > <!-- Date of last revision
-->
- <!ENTITY DOCID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)" >
<!-- Document ID -->
-
- <!-- Group: Miscellaneous -->
-
- <!ENTITY FCLOCALVER "5" > <!-- Local version of Fedora Core for
this document -->
-<!--
- These common entities are useful shorthand
- terms and names, which may be subject to
- change at anytime. This is an important
- value the entity provides, a single location
- to update terms and common names.
--->
-
-<!-- *************** Fedora common entities *************** -->
-<!ENTITY FED "Fedora"> <!-- Generic root term -->
-<!ENTITY CORE "Core"> <!-- Generic root term -->
-<!ENTITY FC "&FED; &CORE;"> <!-- Generic main project name
-->
-<!ENTITY DISTRO "&FC;"> <!-- Legacy entity -->
-<!ENTITY FCX "FC"> <!-- Short project name -->
-<!ENTITY FP "&FED; Project"> <!-- Generic overall project name
-->
-<!ENTITY FDP "&FED; Documentation Project"> <!-- Generic docs
project name -->
-<!ENTITY FDPX "&FED; Docs Project"> <!-- Short docs project name
-->
-<!ENTITY EX "Extras"> <!-- cf. Core -->
-<!ENTITY FEX "&FED; &EX;"> <!-- cf. Fedora Core -->
-
-<!ENTITY FP-URL "<ulink
url='http://www.fedoraproject.org/'/>"> <!-- Fedora Project URL
-->
-<!ENTITY FDP-URL "<ulink
url='http://www.fedoraproject.org/wiki/DocsProject/'/>"> <!-- Fedora
Docs Project URL -->
-<!ENTITY FDPDOCS-URL "<ulink
url='http://docs.fedoraproject.org/'/>"> <!-- Fedora Documentation
(repository) URL -->
-
-<!ENTITY BZ "Bugzilla"> <!-- Bugzilla -->
-<!ENTITY BZ-URL "<ulink
url='http://bugzilla.redhat.com/'>http://bugzilla.redhat.com/&...
<!-- Bugzilla URL -->
-<!ENTITY BZ-PROD "&FED; Documentation"> <!-- Bugzilla product for
Fedora docs -->
-
-<!-- *************** Fedora version numbers *************** -->
-<!ENTITY FCVER "6"> <!-- Current release version of main project
-->
-<!ENTITY TESTVER "test3"> <!-- Current test number of main project
-->
-<!ENTITY FCTESTVER "6 &TESTVER;"> <!-- Current test version of
main project -->
-
-
-<!-- ************** other common names *********** -->
-<!ENTITY RH "Red Hat"> <!-- The generic term "Red Hat"
-->
-<!ENTITY FORMAL-RHI "&RH;, Inc."> <!-- The generic term "Red
Hat, Inc. -->
-<!ENTITY RHL "&RH; Linux"> <!-- The generic term "Red Hat
Linux" -->
-<!ENTITY RHN "&RH; Network"> <!-- The generic term "Red Hat
Network" -->
-<!ENTITY RHEL "&RH; Enterprise Linux"> <!-- The generic term
"Red Hat Enterprise Linux" -->
-
-<!-- ************** technology terms *********** -->
-<!ENTITY SEL "SELinux"> <!-- Generic technology term -->
-
-<!-- ************** common doc files *********** -->
-<!ENTITY LEGALNOTICE SYSTEM "./legalnotice-en_US.xml">
-<!ENTITY LEGALNOTICE-CONTENT SYSTEM "./legalnotice-content-en_US.xml">
-<!ENTITY LEGALNOTICE-OPL SYSTEM "./legalnotice-opl-en_US.xml">
-<!ENTITY LEGALNOTICE-OPL-CONTENT SYSTEM "./opl.xml">
-<!ENTITY LEGALNOTICE-RELNOTES SYSTEM "./legalnotice-relnotes-en_US.xml">
-<!ENTITY LEGALNOTICE-SECTION SYSTEM "./legalnotice-section-en_US.xml">
-<!ENTITY BUG-REPORTING SYSTEM "./bugreporting-en_US.xml">
+<?xml version="1.0" encoding="UTF-8"?>
-<!-- ************** common applications? *********** -->
+<!-- $Id: -->
-<!-- ************** required by build scripts *********** -->
-
-<!ENTITY PROJECT "&FP;">
-
-<!-- ************** tutorial titles ********** -->
-
-<!ENTITY IG "Installation Guide">
-<!ENTITY DOCG "Documentation Guide">
-
-<!-- ************** tutorial URLs *********** -->
-
-<!ENTITY IG-URL "<ulink
url='http://docs.fedoraproject.org/install-guide/'/>">
-<!ENTITY DOCG-URL "<ulink
url='http://docs.fedoraproject.org/documentation-guide/'/>&quo...
-
-<!-- ************** status notices ************* -->
-<!ENTITY DRAFTNOTICE SYSTEM "./draftnotice-en_US.xml">
-<!ENTITY LEGACYNOTICE SYSTEM "./legacynotice-en_US.xml">
-<!ENTITY OBSOLETENOTICE SYSTEM "./obsoletenotice-en_US.xml">
-<!ENTITY DEPRECATEDNOTICE SYSTEM "./deprecatednotice-en_US.xml">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+<!-- *************** COMMON FDP entities *************** -->
+<!ENTITY % FDP-ENTITIES SYSTEM "fdp-entities.ent">
+ %FDP-ENTITIES;
]>
-<article id="yum-software-management" lang="en_US">
-<articleinfo>
- <title>Managing Software with yum</title>
- <copyright>
- <year>2006</year>
- <holder>Stuart Ellis</holder>
- </copyright>
- <authorgroup>
- <author>
- <surname>Ellis</surname>
- <firstname>Stuart</firstname>
- </author>
- <editor>
- <surname>Frields</surname>
- <firstname>Paul</firstname>
- <othername>W.</othername>
- </editor>
- </authorgroup>
- <revhistory>
- <revision>
- <revnumber>1.31</revnumber>
- <date>2006-04-30</date>
- <authorinitials>StuartEllis</authorinitials>
- <revdescription>
- <para>
- Amended search section.
- </para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>1.3</revnumber>
- <date>2006-03-24</date>
- <authorinitials>StuartEllis</authorinitials>
- <revdescription>
- <para>
- Minor restructuring of sections.
- </para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>1.2</revnumber>
- <date>2006-03-19</date>
- <authorinitials>StuartEllis</authorinitials>
- <revdescription>
- <para>
- Added sections on caching and plugins.
- </para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>1.1</revnumber>
- <date>2006-03-13</date>
- <authorinitials>StuartEllis</authorinitials>
- <revdescription>
- <para>
- Updated for Fedora 5.
- </para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>1.0.5</revnumber>
- <date>2005-11-28</date>
- <authorinitials>PaulFrields</authorinitials>
- <revdescription>
- <para>
- Fixed some uses of "Fedora" to read "Fedora Core" where
- appropriate.
- </para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>1.0.4</revnumber>
- <date>2005-11-15</date>
- <authorinitials>StuartEllis</authorinitials>
- <revdescription>
- <para>
- Updated section on proxy servers. Fixed #166122.
- </para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>1.0.3</revnumber>
- <date>2005-10-13</date>
- <authorinitials>PaulFrields</authorinitials>
- <revdescription>
- <para>
- Fix wording (#170584).
- </para>
- </revdescription>
- </revision>
[...2077 lines suppressed...]
- </note>
- </section>
-
- <section id="sn-yum-clearance">
- <title>Clearing the <command>yum</command> Caches</title>
- <indexterm>
- <primary>caching</primary>
- <secondary>cleaning caches</secondary>
- </indexterm>
- <indexterm>
- <primary>yum</primary>
- <secondary>cleaning caches</secondary>
- </indexterm>
- <para>
- If you configure it to do so, <command>yum</command> retains the
- packages and package data files that it downloads, so that they
- may be reused in future operations without being downloaded
- again. To purge the package data files, use this command:
- </para>
-<screen>
-<userinput>su -c 'yum clean headers'</userinput>
-</screen>
- <para>
- Run this command to remove all of the packages held in the
- caches:
- </para>
-<screen>
-<userinput>su -c 'yum clean packages'</userinput>
-</screen>
- <para>
- When using these commands, at the prompt, enter the password for
- the <systemitem class="username">root</systemitem>
account.
- </para>
-
- <para>
- Purging cached files causes those files to downloaded again the
- next time that they are required. This increases the amount of
- time required to complete the operation.
- </para>
- </section>
- </section>
-
- <section id="sn-yum-proxy-server">
- <title>Using <command>yum</command> with a Proxy
Server</title>
- <indexterm>
- <primary>proxy server</primary>
- </indexterm>
- <indexterm>
- <primary>yum</primary>
- <secondary>using with a proxy server</secondary>
- </indexterm>
- <para>
- By default, <command>yum</command> accesses network repositories
- with HTTP. All <command>yum</command> HTTP operations use
- HTTP/1.1, and are compatible with web proxy servers that support
- this standard. You may also access FTP repositories, and configure
- <command>yum</command> to use an FTP proxy server. The
- <filename>squid</filename> package provides a proxy service for
- both HTTP/1.1 and FTP connections.
- </para>
- <tip>
- <title>Modifying <command>yum</command> for Network
Compatibility</title>
- <para>
- Refer to the <command>man</command> page for
- <filename>yum.conf</filename> for information on HTTP settings
- that may be modified for compatibility with nonstandard web
- proxy servers. Alternatively, configure <command>yum</command>
- to use an FTP proxy server, and access repositories that support
- FTP. The &FED; repositories support both HTTP and FTP.
- </para>
- </tip>
- <section id="sn-yum-proxy-server-global">
- <title>Configuring Proxy Server Access</title>
-
- <para>
- To enable all <command>yum</command> operations to use a proxy
- server, specify the proxy server details in
- <filename>/etc/yum.conf</filename>. The
<option>proxy</option>
- setting must specify the proxy server as a complete URL,
- including the TCP port number. If your proxy server requires a
- username and password, specify these by adding
- <option>proxy_username</option> and
- <option>proxy_password</option> settings.
- </para>
-
- <para>
- The settings below enable <command>yum</command> to use the
- proxy server
- <systemitem
- class="systemname">mycache.mydomain.com</systemitem>,
- connecting to port 3128, with the username
- <systemitem
- class="username">yum-user</systemitem> and the
- password <systemitem>qwerty</systemitem>.
- </para>
-
- <example id="config-file-httpproxy">
- <title>Configuration File Settings for Using A Proxy Server</title>
-<screen>
-<computeroutput># The proxy server - proxy server:port number
-proxy=http://mycache.mydomain.com:3128
-# The account details for yum connections
-proxy_username=yum-user
-proxy_password=qwerty</computeroutput>
-</screen>
- </example>
-
- <note>
- <title>Global Settings</title>
-
- <para>
- If you define a proxy server in
- <filename>/etc/yum.conf</filename>,
<emphasis>all</emphasis>
- users connect to the proxy server with those details when
- using <command>yum</command>.
- </para>
- </note>
- </section>
-
- <section id="sn-yum-proxy-server-peruser">
- <title>Configuring Proxy Server Access for a Single User</title>
-
- <para>
- To enable proxy access for a specific user, add the lines in the
- example box below to the user's shell profile. For the default
- <command>bash</command> shell, the profile is the file
- <filename>~/.bash_profile</filename>. The settings below enable
- <command>yum</command> to use the proxy server
- <systemitem
- class="systemname">mycache.mydomain.com</systemitem>,
- connecting to port 3128.
- </para>
-
- <example id="profile-script-httpproxy">
- <title>Profile Settings for Using a Proxy Server</title>
-<screen>
-<computeroutput># The Web proxy server used by this account
-http_proxy="http://mycache.mydomain.com:3128"
-export http_proxy</computeroutput>
-</screen>
- </example>
-
- <para>
- If the proxy server requires a username and password, add these
- to the URL. To include the username
- <systemitem class="username">yum-user</systemitem> and the
- password <systemitem>qwerty</systemitem>, add these settings:
- </para>
-
- <example id="profile-script-httpproxy-withpassword">
- <title>Profile Settings for a Secured Proxy Server</title>
-<screen>
-<computeroutput># The Web proxy server, with the username and password for this
account
-http_proxy="http://yum-user:qwerty@mycache.mydomain.com:3128"
-export http_proxy</computeroutput>
-</screen>
- </example>
-
- <note>
- <title>The <option>http_proxy</option> Environment
Variable</title>
-
- <para>
- The <command>http_proxy</command> environment variable is also
- used by <command>curl</command> and other utilities. Although
- <command>yum</command> itself may use
- <command>http_proxy</command> in either upper-case or
- lower-case, <command>curl</command> requires the name of the
- variable to be in lower-case.
- </para>
- </note>
- </section>
- </section>
-
-<!-- SE: This is at the end of the document, since it looks out of place in section 1
-->
-
- <section id="sn-acknowledgments">
- <title>Acknowledgments</title>
-
- <para>
- Paul Frields edited this document. Timothy Murphy reviewed the
- beta release.
- </para>
- </section>
-
- <index id="generated-index"></index>
+ <xi:include href="introduction.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="concepts.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="tools.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="manage-with-yum.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="search-with-yum.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="update-with-yum.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="configuring-repositories.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="isolated-install.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="customizing-yum.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="pup.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="pirut.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="yum-caching.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="yum-proxy.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index/>
</article>