xml-normalize yum-software-management-en.xml,NONE,1.1
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Mon Jun 27 18:33:37 UTC 2005
Author: pfrields
Update of /cvs/docs/xml-normalize
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv13067
Added Files:
yum-software-management-en.xml
Log Message:
Using xmlformat in tidy-bowl, testing commences...
--- NEW FILE yum-software-management-en.xml ---
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../docs-common/common/fedora-entities-en.ent">
%FEDORA-ENTITIES-EN;
<!ENTITY BOOKID "yum-software-management-0.4.4 (2005-06-14)"> <!-- change version of manual and date here -->
<!ENTITY LEGALNOTICE SYSTEM "../docs-common/common/legalnotice-en.xml">
<!-- Bugzilla bug number for the draft notice -->
<!ENTITY BUG-NUM "155190">
<!ENTITY FCLOCALVER "3">
<!ENTITY DRAFTNOTICE SYSTEM "../docs-common/common/draftnotice-en.xml">
]>
<article id="yum-software-management" lang="en">
<articleinfo>
<title>Software Management with <command>yum</command></title>
<copyright>
<year>2005</year>
<holder>Stuart Ellis</holder>
</copyright>
<authorgroup>
<author>
<surname>Ellis</surname>
<firstname>Stuart</firstname>
</author>
</authorgroup>
&LEGALNOTICE;
<revhistory>
<revision>
<revnumber>0.4</revnumber>
<date>2005-06-01</date>
<authorinitials>StuartEllis</authorinitials>
<revdescription>
<para>
Initial import into CVS.
</para>
</revdescription>
</revision>
</revhistory>
</articleinfo>
<section id="sn-introduction">
<title>Introduction</title>
&DRAFTNOTICE;
<section id="sn-audience">
<title>Audience</title>
<para>
The <command>yum</command> utility is currently the recommended
method for managing software on &FED; systems. All &FED; users
responsible for maintaining their own systems will find
<command>yum</command> an essential tool.
</para>
</section>
<section id="sn-usingdoc">
<title>Using This Document</title>
<para>
This document is a reference for using <command>yum</command>.
You may wish to read some or all of the sections, depending upon
your needs and level of experience.
</para>
<para>
If you are a new user, read the
<xref
linkend="sn-software-management-concepts"/> before
using <command>yum</command> for the first time.
</para>
<para>
Experienced Linux users should start with
<xref linkend="sn-authorizing-package-sources"/>.
</para>
<para>
Anyone with several &FED; systems on a network may benefit from
setting up their own software repositories to manage the process
of installation and updates. The details of maintaining your own
repositories are explained in
<xref linkend="sn-managing-repositories"/>.
</para>
<para>
Most of the examples use the package
<filename>tsclient</filename>, which is included with &FC; to
provide an application for remote desktop access. If it is
installed successfully you may start the application by choosing
<menuchoice><guimenu>Applications</guimenu><guisubmenu>Internet</guisubmenu><guimenuitem>Terminal
Server Client</guimenuitem></menuchoice>. To use the examples,
substitute the name of the relevant package for
<filename>tsclient</filename>.
</para>
<important>
<title>Avoid Logging in with the Root Account</title>
<para>
You do not need to log in with the root account in order to
manage your &FC; system. All of the commands shown in this
tutorial that require root access will prompt you for the root
password. The example terminal commands use <command>su
<option>-c</option></command> to provide this facility.
</para>
</important>
</section>
<section id="sn-yum-additional-resources">
<title>Additional Resources</title>
<para>
The <command>yum</command> utility has features and options that
are not discussed in this document. Read the
<command>man</command> pages for <command>yum(8)</command> and
<filename>yum.conf(5)</filename> to learn more.
</para>
<para>
The official Website for <command>yum</command> is:
</para>
<para>
<ulink url="http://linux.duke.edu/projects/yum/">http://linux.duke.edu/projects/yum/</ulink>
</para>
<para>
The official mailing list for <command>yum</command> users is:
</para>
<para>
<ulink url="https://lists.dulug.duke.edu/mailman/listinfo/yum">https://lists.dulug.duke.edu/mailman/listinfo/yum</ulink>
</para>
<para>
The archive for the <command>yum</command> development mailing
list is here:
</para>
<para>
<ulink url="https://lists.dulug.duke.edu/pipermail/yum-devel/">https://lists.dulug.duke.edu/pipermail/yum-devel/</ulink>
</para>
</section>
</section>
<section id="sn-software-management-concepts">
<title>Software Management Concepts</title>
<section id="sn-about-packages">
<title>About Packages</title>
<para>
All of the software and documentation prepared for use with
&FED; is supplied in the form of files called RPM
<indexterm>
<primary>packages</primary>
<secondary>defined</secondary>
</indexterm>
<firstterm>packages</firstterm>. Each package is a compressed
archive containing product information, program files, icons,
documentation and management scripts. Packages also include a
digital signature to prove their source. These files are used by
management applications to safely locate, install, update and
remove software. For example, the &FED; installation process
uses the packages supplied with &FC; to build or upgrade a
system to your requirements.
</para>
</section>
<section id="sn-about-repositories">
<title>About Repositories</title>
<para>
Software management utilities like <command>yum</command> are
not intended to enable you to install a specific package file.
Instead, they automatically locate and obtain the correct RPM
packages for an application from
<indexterm>
<primary>repositories</primary>
<secondary>defined</secondary>
</indexterm>
<firstterm>repositories</firstterm>, which are prepared
directories or Websites.
</para>
<para>
The package management utilities in &FC; are automatically
configured to use the network of repository servers maintained
by the &FP;. These repositories hold both the software included
with &FC;, and a large selection of additional software, known
as &FEX;. Third-party software developers also provide
repositories for their &FED; compatible packages.
</para>
<para>
This method frees you from having to manually find and install
new applications or updates: you may use a single command to
update all of the software that makes up your system, or to
search for new software by specifying criteria. In each case the
management utility connects to the repositories that it is
configured to use, and checks the indexes that they provide to
find the correct packages.
</para>
<para>
Using repositories also ensures also that you always receive the
current version of the software. If several versions of the same
package are available then your management utility automatically
selects the latest version.
</para>
<para>
For these reasons you should only manually install software when
you are confident that there is no repository that can currently
provide it. If a piece of software on your system is not
available from a repository then no update feature can
automatically find or install newer versions, and you must keep
that product updated yourself.
</para>
<note>
<title>All &FED; Packages are Free Software</title>
<para>
All of the software provided by the &FP; is Free Software, or
Open Source, and can therefore be downloaded and installed
from the network of &FED; repositories without restrictions.
</para>
</note>
</section>
<section id="sn-about-dependencies">
<title>About Dependencies</title>
<para>
You must consider package
<indexterm>
<primary>dependencies</primary>
</indexterm>
<firstterm>dependencies</firstterm> when manually installing
software. To avoid conflicts and inconsistencies Linux
distributions supply program library files as separate packages
to the applications that use their functions. Many libraries and
command-line utilities are used by multiple applications.
</para>
<para>
Management tools like <command>yum</command> use the information
on dependencies stored within packages to ensure that all of the
requirements are met when you install an application. The
packages for any supporting software are automatically be
installed first, if they are not already present on your system.
If a new application has requirements that conflict with
existing software then the installation process safely aborts
without making any changes to your system.
</para>
</section>
<section id="sn-package-names">
<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
package supplied with &FC;:
</para>
<screen>
<filename>tsclient-0.132-4.i386.rpm</filename>
</screen>
<para>
Use just the name of the package itself with
<command>yum</command>, except when it is necessary to specify
the exact version or type. To specify the exact version of the
application, use <filename>name-version</filename>. The package
listings provided by <command>yum</command> itself use the
format <filename>name.architecture</filename>, to specify the
type of computer that the package is intended for.
</para>
<para>
These are valid for the file shown above:
</para>
<itemizedlist>
<listitem>
<para>
Package name: <filename>tsclient</filename>
</para>
</listitem>
<listitem>
<para>
Package name with version number:
<filename>tsclient-0.132</filename>
</para>
</listitem>
<listitem>
<para>
Package name with hardware architecture:
<filename>tsclient.i386</filename>
</para>
</listitem>
</itemizedlist>
<para>
The hardware architecture is the <emphasis>minimum</emphasis>
type of machine required for that specific package. Packages
with <option>i386</option> run on any current Intel-compatible
computer. Packages for PowerPC machines, such as Apple Macs, are
indicated with <option>ppc</option>. Packages with
<option>noarch</option> have no architecture requirement.
</para>
<para>
Some software can be optimized for particular types of
Intel-compatible machine, and separate packages are provided for
<option>i386</option>, <option>i586</option>,
<option>i686</option> and <option>x86_64</option>. A computer
with at least an Intel Pentium, VIA C3 or compatible chip is an
<option>i586</option>. Computers with an Intel Pentium II and
above, or a current model of AMD chip, are <option>i686</option>
machines. 64-bit PCs use <option>x86_64</option> packages for
full 64-bit support.
</para>
<note>
<title>Other Naming Conventions are Supported</title>
<para>
Refer to <xref linkend="sn-searching-packages-byname"/> for
more information on specifying packages by name or type.
</para>
</note>
</section>
</section>
<section id="sn-software-management-tools">
<title>Software Management Tools in &FC;</title>
<para>
The <command>yum</command> utility is a complete software
management system. &FC; also includes other several other
applications that can supplement <command>yum</command>.
</para>
<para>
On your desktop is an
<indexterm>
<primary>up2date</primary>
<secondary>alert icon</secondary>
</indexterm>
<application>alert icon</application> that keeps you informed
about package updates. Until your system is updated this appears
as a red circle with a flashing exclamation mark. The alert icon
is integrated with
<indexterm>
<primary>up2date</primary>
</indexterm>
<application>up2date</application>, which enables you to easily
install updates for your system.
</para>
<para>
Both <application>up2date</application> and <command>yum</command>
are configured to use official &FED; repositories. If you add
other repositories to <command>yum</command> then for consistency
you should also configure <application>up2date</application> to
use them.
</para>
<para>
Also included in &FC; is
<indexterm>
<primary>system-config-packages</primary>
</indexterm>
<indexterm>
<primary>Add/Remove Applications</primary>
<see>system-config-packages</see>
</indexterm>
<application>system-config-packages</application>. From the main
menu, this is <menuchoice><guimenu>System
Settings</guimenu><guimenuitem>Add/Remove
Applications</guimenuitem></menuchoice>. Unlike
<application>up2date</application> and <command>yum</command>, it
installs software packages from your &FC; installation discs, and
does not use repositories. You may find this application useful
for systems that do not have a network connection.
</para>
<para>
The <command>rpm</command> command-line utility has many functions
for working with individual RPM packages, and can also be used to
manually install and remove packages from your system. Installing
software with the <command>rpm</command> utility can be difficult,
and is not recommended.
</para>
<caution>
<title>Current Package Versions</title>
<para>
Using <application>up2date</application> and
<command>yum</command> ensures that you have the most recent
version of the packages that are being installed. Other methods
do not guarantee that the packages are current.
</para>
</caution>
</section>
<section id="sn-authorizing-package-sources">
<title>Authorizing Package Sources</title>
<para>
All of the packages that you install should be digitally signed to
prove their source. By default, <command>yum</command> does not
install packages unless their digital signature matches a GPG
public key on the <command>rpm</command> keyring.
</para>
<para>
No keys are automatically included on the keyring. You must
manually
<indexterm>
<primary>GPG public keys</primary>
<secondary>adding</secondary>
</indexterm>
add the public key for &FP; packages, which is the file
<filename>/usr/share/rhn/RPM-GPG-KEY-fedora</filename>.
</para>
<para>
To import this public key, type the following:
</para>
<screen>
<userinput>su -c 'rpm --import <replaceable>/usr/share/rhn/RPM-GPG-KEY-fedora</replaceable>'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
<para>
Other public keys can be added in the same way. You can also
import public keys directly from a Website. For example, to import
the file <filename>GPG-PUB-KEY.asc</filename> on the website
<wordasword>www.therepository.com</wordasword> the command would
be:
</para>
<screen>
<userinput>su -c 'rpm --import <replaceable>http://www.therepository.com/GPG-PUB-KEY.asc</replaceable>'</userinput>
</screen>
<note>
<title>Public Keys and <application>up2date</application></title>
<para>
The <application>up2date</application> utility automatically
uses the public key for &FC; packages. It does not add the
public key to the keyring that is used by both
<command>yum</command> and the <command>rpm</command> utility.
</para>
</note>
</section>
<section id="sn-updating-your-system">
<title>Updating Your System with <command>yum</command></title>
<para>
You may update all of the software that makes up your &FC; system
in a single operation. This is done with the
<option>update</option> function.
</para>
<para>
To carry out a full system update, type this command in a terminal
window:
</para>
<screen>
<userinput>su -c 'yum update'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
<para>
Data files are downloaded from each of the repositories that
<command>yum</command> is configured to use. These index and
header files are searched for information about newer versions of
packages. On a slow connection the download process may take
several seconds.
</para>
<para>
A list of all of the available updates for your system is
displayed. Press <userinput>y</userinput> to accept the updates.
If you accept the updates the relevant packages are then
downloaded and installed.
</para>
<section id="sn-automatic-updating">
<title>Automatically Updating Your System</title>
<para>
If your system is permanently connected to the network then
updates can be performed at any time. The
<filename>yum</filename> package includes scripts that can
automatically carry out full updates every day.
</para>
<para>
To activate automatic daily updating, type this line:
</para>
<screen>
<userinput>su -c '/sbin/chkconfig --level 345 yum on; /sbin/service yum start'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
<note>
<title>How Daily Updates are Run</title>
<para>
There is no separate <command>yum</command> service that runs
on your system. The command given above enables the control
script <filename>/etc/rc.d/init.d/yum</filename>. This control
script activates the script
<filename>/etc/cron.daily/yum.cron</filename>, so that the
<command>cron</command> service will perform the system update
as one of the tasks that are automatically run each day.
</para>
</note>
</section>
</section>
<section id="sn-searching-packages">
<title>Searching for Software with <command>yum</command></title>
<para>
You may use <command>yum</command> to find software that is
available from the defined repositories, or is already installed
on your system. Searches automatically include both installed and
available packages.
</para>
<note>
<title>Searches are not Case-sensitive</title>
<para>
The <option>search</option> and <option>list</option> options of
<command>yum</command> are not case-sensitive. For example, a
query for <filename>palmpilot</filename> will automatically find
<filename>PalmPilot</filename> packages.
</para>
</note>
<section id="sn-searching-packages-byname">
<title>Searching by Package Name and Attributes</title>
<para>
To search for a specific package by name, use the
<option>list</option> function. For example, to search for the
package <filename>tsclient</filename> the command would be:
</para>
<screen>
<userinput>yum list <replaceable>tsclient</replaceable></userinput>
</screen>
<para>
To make your queries more specific, add other package
attributes. For example, to search for version 0.132 of the
application the command would be:
</para>
<screen>
<userinput>yum list <replaceable>tsclient-0.132</replaceable></userinput>
</screen>
<tip>
<title>Package Attributes</title>
<para>
You may use any of the following formats for specifying a
package in a <command>yum</command> query:
<filename>name</filename>,
<filename>name.architecture</filename>,
<filename>name-version</filename>,
<filename>name-version-release</filename>,
<filename>name-version-release.architecture</filename>, and
<filename>epoch:name-version-release.architecture</filename>.
</para>
</tip>
</section>
<section id="sn-searching-packages-advanced">
<title>Advanced Searches</title>
<para>
If you do not know the name of the package, use either the
<option>search</option> or <option>provides</option> options.
<option>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 PalmPilots, type:
</para>
<screen>
<userinput>yum search <replaceable>PalmPilot</replaceable></userinput>
</screen>
<para>
The <option>provides</option> function checks both the files
included in the packages and the functions that the software
provides. This option requires <command>yum</command> to
download and read much larger index files than other types of
search.
</para>
<para>
To search for all packages that include files called
<filename>libneon</filename> you type:
</para>
<screen>
<userinput>yum provides <replaceable>libneon</replaceable></userinput>
</screen>
<para>
To search for all packages that either provide an MTA (Mail
Transport Agent) service, or include files with
<filename>mta</filename> in their name:
</para>
<screen>
<userinput>yum provides <replaceable>MTA</replaceable></userinput>
</screen>
<tip>
<title>Wildcards and Regular Expressions</title>
<para>
You may use the standard wildcard characters in search
criteria: <option>?</option> to represent any one character,
and <option>*</option> to mean any characters. Use Perl or
Python regular expressions to carry out more complex queries.
</para>
</tip>
</section>
<section id="sn-package-matches">
<title>Understanding Matches</title>
<para>
When carrying out a search <command>yum</command> shows all of
the packages that match your criteria. Packages must meet the
terms of the search exactly to be considered matches, unless you
have used wildcards or a regular expression.
</para>
<para>
For example, querying for <filename>shadowutils</filename> or
<filename>shadow-util</filename> would not produce the package
<filename>shadow-utils</filename>. This package would match and
be shown if the query was either
<filename>shadow-util?</filename> or
<filename>Shadow*</filename>.
</para>
<para>
When several versions of the same package are available, only
the newest is used.
</para>
</section>
</section>
<section id="sn-managing-packages">
<title>Managing Software Packages with <command>yum</command></title>
<indexterm>
<primary>yum, package management</primary>
</indexterm>
<para>
The <command>yum</command> utility has three basic management
functions:
</para>
<para>
<itemizedlist>
<listitem>
<para>
<option>install</option> new software packages.
</para>
</listitem>
<listitem>
<para>
<option>update</option> existing software.
</para>
</listitem>
<listitem>
<para>
<option>remove</option> unwanted software.
</para>
</listitem>
</itemizedlist>
</para>
<para>
In each case you must specify the function and the criteria. Some
simple examples are given in each section.
</para>
<note>
<title>Search Criteria</title>
<para>
See <xref linkend="sn-searching-packages"/> for details of
search criteria. The management options of
<command>yum</command> <emphasis>are</emphasis> case-sensitive.
</para>
</note>
<para>
As with the search and system update functions,
<command>yum</command> begins the process by downloading data
files from each of the repositories that it is configured to use.
Once <command>yum</command> has determined the steps to carry out
the task you are presented with the proposed package changes,
which you can either approve or reject. By default no changes are
made to your system unless you approve.
</para>
<tip>
<title>Downloaded Packages</title>
<para>
The RPM packages downloaded and used by <command>yum</command>
are held in sub-directories of
<filename>/var/cache/yum/</filename>, with one sub-directory per
repository. You may copy these cached packages and use them
elsewhere if you wish. Removing a package from your system does
not delete the downloaded RPM from the cache. See
<xref
linkend="sn-yum-clearance"/> for details on
purging the caches.
</para>
</tip>
<section id="sn-yum-installing-packages">
<title>Installing a New Software Package with <command>yum</command></title>
<indexterm>
<primary>installing software with yum</primary>
</indexterm>
<indexterm>
<primary>packages, installing</primary>
</indexterm>
<para>
To install or update software, <command>yum</command> examines
the package caches on your system and each of the configured
package sources to determine the best set of actions to produce
the required result. This may include installing or updating
other packages in addition to the package that you specified.
</para>
<para>
To install the package <filename>tsclient</filename>, enter the
command:
</para>
<screen>
<userinput>su -c 'yum install <replaceable>tsclient</replaceable>'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
</section>
<section id="sn-yum-updating-packages">
<title>Updating a Software Package with <command>yum</command></title>
<indexterm>
<primary>updating software with yum</primary>
</indexterm>
<indexterm>
<primary>packages, updating</primary>
</indexterm>
<para>
Updating a software package follows the same process as
installing a new package. For example, to update the
<filename>tsclient</filename> package to the latest version,
type:
</para>
<screen>
<userinput>su -c 'yum update <replaceable>tsclient</replaceable>'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
</section>
<section id="sn-yum-removing-packages">
<title>Removing Software with <command>yum</command></title>
<indexterm>
<primary>removing software with yum</primary>
</indexterm>
<indexterm>
<primary>packages, removing</primary>
</indexterm>
<para>
To remove software, <command>yum</command> examines your system
for both the specified software, and any other software that
must also be removed in order to safely uninstall it.
</para>
<para>
To remove the <filename>tsclient</filename> package from your
system the full command is:
</para>
<screen>
<userinput>su -c 'yum remove <replaceable>tsclient</replaceable>'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
</section>
</section>
<section id="sn-using-repositories">
<title>Using Other Software Repositories</title>
<indexterm>
<primary>&FEX;</primary>
</indexterm>
<indexterm>
<primary>repositories, finding</primary>
</indexterm>
<indexterm>
<primary>searching for repositories</primary>
</indexterm>
<para>
Projects and individuals that provide RPM packages through
<command>yum</command> repositories will provide details on their
Website. The &FEX; project is the official source for additional
packages.
</para>
<para>
The Website for &FEX; is here:
</para>
<para>
<ulink url="http://fedora.redhat.com/projects/extras/">http://fedora.redhat.com/projects/extras/</ulink>
</para>
<note>
<title>Repositories for Early Versions of &FC;</title>
<para>
&FEX; does not provides packages for &FC; 2 or earlier. The
official Website for additional packages for &FC; 1 and &FC; 2
is:
<ulink url="http://www.fedora.us/">http://www.fedora.us/</ulink>
</para>
</note>
<para>
You should use these sites for software that is not included with
&FC;. If these sites do not provide packages for a specific piece
of software, the manufacturer of the software may provide or
recommend a repository.
</para>
<section id="sn-adding-repositories">
<title>Adding a Repository as a Package Source</title>
<indexterm>
<primary>repositories, adding to yum</primary>
</indexterm>
<indexterm>
<primary>repository definition files, installing</primary>
</indexterm>
<para>
&FC; includes a <filename>yum</filename> package that has &FED;
repositories in the configuration. To add an extra repository,
place a definition file in the
<filename>/etc/yum.repos.d/</filename> directory on your system.
Package providers make the definition files for their
repositories available on their Websites.
</para>
<tip>
<title>Definition File Extension</title>
<para>
The names of repository definition files end with
<filename>.repo</filename>.
</para>
</tip>
<para>
Adding a file to the definitions directory requires root access.
To copy the definition file <filename>example.repo</filename>,
type the command:
</para>
<screen>
<userinput>su -c 'cp example.repo /etc/yum.repos.d/'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
<para>
You must also add the public key of the package provider, if you
have not not already imported it. The process is described in
<xref linkend="sn-authorizing-package-sources"/>.
</para>
<note>
<title>Repositories and <application>Up2date</application> Channels</title>
<para>
You should also add new package repositories as
<application>up2date</application> channels to ensure
consistency between the behavior of the two applications.
</para>
</note>
</section>
<section id="sn-compat-repositories">
<title>Understanding Repository Compatibility</title>
<indexterm>
<primary>packages, software compatibility</primary>
</indexterm>
<indexterm>
<primary>repositories, compatibility</primary>
</indexterm>
<para>
The &FEX; project provides packages that are built to the same
standards as the packages that are part of &FC;. Third-party
packages should be compatible with these official packages,
unless the provider specifically states otherwise.
</para>
<para>
You should still always check the Website of the provider for
compatibility information before attempting to use a repository.
Repositories often provide packages that are specifically
intended for use with packages that are supplied by other
repositories. In some cases separate third-party repository
providers may each offer different versions of the same
software, preventing those repositories from being safely used
together by your &FC; system.
</para>
<para>
Packages that have been made for one version of &FC; are usually
not compatible with other versions of &FC;. The Website of the
provider should specifically state which versions of &FC; they
support.
</para>
<tip>
<title>Old Versions of <command>yum</command> and Current Repositories</title>
<para>
The data format for repository indexes changed with version
2.11 of <command>yum</command>. This was the version supplied
with &FC; 3. Repository providers should specify the versions
of &FC; that they support. All repositories compatible with
current versions of <command>yum</command> can also be
identified by the fact that they have a sub-directory called
<filename>repo-data/</filename>.
</para>
</tip>
</section>
</section>
<section id="sn-yum-maintenance">
<title>Maintaining <command>yum</command></title>
<para>
The <command>yum</command> system does not require any routine
maintenance. It is useful to disable or remove repository
definitions that are no longer required, as each repository that
is defined and enabled is checked for every operation. You may
also wish to periodically remove files relating to unwanted
packages, in order to save disk space.
</para>
<section id="sn-removing-sources">
<title>Disabling or Removing Package Sources</title>
<indexterm>
<primary>repositories, disabling in yum</primary>
</indexterm>
<indexterm>
<primary>repositories, removing from yum</primary>
</indexterm>
<indexterm>
<primary>repository definition files, removing</primary>
</indexterm>
<para>
Set <command>enable=0</command> in a definition file to prevent
<command>yum</command> using that repository. Any definition
file with this setting is ignored.
</para>
<para>
To completely remove access to a repository:
</para>
<orderedlist>
<listitem>
<para>
Delete the relevant file from
<filename>/etc/yum.repos.d/</filename>.
</para>
</listitem>
<listitem>
<para>
Delete the cache directory from
<filename>/var/cache/yum/</filename>.
</para>
</listitem>
</orderedlist>
<indexterm>
<primary>public keys, removing</primary>
</indexterm>
<para>
If you will not be using any more packages from that source then
you should also remove their public key from the
<command>rpm</command> keyring. To remove a public key you first
need to know the identification name used by
<command>rpm</command>. You may view the details of all public
keys with the command:
</para>
<screen>
<userinput>rpm -qi gpg-pubkey-*</userinput>
</screen>
<para>
The identification name for a key is
<option>gpg-pubkey-Version_number-Release_number</option>. For
example, the &FP; public key is currently version 4f2a6fd2,
release 3f9d9d3b. The <command>rpm</command> identification for
this key is <option>gpg-pubkey-4f2a6fd2-3f9d9d3b</option>.
</para>
<para>
Once you know the identification name of the key, use the
command <command>rpm <option>-e</option></command> to remove it.
To remove the &FP; public key shown above the exact command
would be:
</para>
<screen>
<userinput>su -c 'rpm -e <replaceable>gpg-pubkey-4f2a6fd2-3f9d9d3b</replaceable>'</userinput>
</screen>
<para>
Enter the root password when prompted.
</para>
</section>
<section id="sn-yum-clearance">
<title>Clearing the <command>yum</command> Caches</title>
<indexterm>
<primary>yum, cleaning caches</primary>
</indexterm>
<para>
By design, <command>yum</command> does not automatically delete
any of the packages or package header files that it downloads,
so that these can be reused. Header files accumulate over time,
and these may be purged with the 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>
In both cases, enter the root password when prompted.
</para>
</section>
</section>
<section id="sn-managing-repositories">
<title>Managing <command>yum</command> Repositories</title>
<para>
You may wish to create your own software repositories, or maintain
a copy of another repository.
</para>
<caution>
<title>Old versions of yum use a different repository utility</title>
<para>
These procedures are for repositories that are compatible with
version 2.11 of <command>yum</command> and above. You must use
the <command>yum-arch</command> utility that was included with
<command>yum</command> 2.10 to enable repositories for older
versions of <command>yum</command>.
</para>
</caution>
<section id="sn-creating-repository">
<title>Creating a New Repository</title>
<indexterm>
<primary>repositories, creating</primary>
</indexterm>
<para>
A software repository is simply a directory containing package
files, with a sub-directory for the package index files used by
<command>yum</command>. Other types of files can be held in the
main directory without interfering with use of the repository.
The <filename>data/</filename> sub-directory and the XML files
it contains are created and updated with the
<command>createrepo</command> utility
</para>
<note>
<title>Creating Repositories Requires an Extra Package</title>
<para>
You must install the <filename>createrepo</filename> package
from &FC; in order to be able to make repositories.
</para>
</note>
<para>
To make a directory into a <command>yum</command> repository:
<orderedlist>
<listitem>
<para>
Copy the RPM packages that you are distributing into the
directory.
</para>
</listitem>
<listitem>
<para>
Open a terminal window.
</para>
</listitem>
<listitem>
<para>
In the terminal window type: <userinput>createrepo
/path/to/directory</userinput>. Substitute the path to
your package directory for
<filename>/path/to/directory/</filename>.
</para>
</listitem>
<listitem>
<para>
In the terminal window type: <userinput>chmod a+x
/path/to/directory/repodata/</userinput>. Substitute the
path to your package directory for
<filename>/path/to/directory/</filename>.
</para>
</listitem>
<listitem>
<para>
Ensure that the directory is available via your chosen
network protocols.
</para>
</listitem>
</orderedlist>
</para>
<para>
The repository is now ready for use.
</para>
<para>
Create a definition file for this new repository. If you are
distributing packages that you have created yourself then you
also need to make the GPG public key for your signature
available, so that others can verify the packages. The simplest
way to make these files available is to put the public key and
repository definition files on the same Website or FTP site as
the repository.
</para>
<para>
Creating a definition file is described in
<xref
linkend="sn-writing-repodefs"/>. Packaging building is
beyond the scope of this document.
</para>
<tip>
<title>Repositories and Management Utilities</title>
<para>
The <command>createrepo</command> utility makes no changes to
the directory other than adding a
<filename>repo-data/</filename> sub-directory. Adding index
files for other utilities does not interfere with
<command>yum</command>.
</para>
</tip>
</section>
<section id="sn-writing-repodefs">
<title>Repository Definition Files</title>
<indexterm>
<primary>repository definition files, creating</primary>
</indexterm>
<indexterm>
<primary>repository definition files, editing</primary>
</indexterm>
<para>
Create and edit repository definition files with a text editor.
Definition files are plain-text with a standard format:
</para>
<example id="yum-repo-format">
<title>Format of <command>yum</command> Repository Definition Files</title>
<programlisting>
<![CDATA[
[serverid]
name=Some longer name and description for this repository
baseurl=url://path/to/repository-copy-1/
url://path/to/repository-copy-2/
enable=(0 or 1)
gpgcheck=(0 or 1)
]]>
</programlisting>
</example>
<para>
The <command>baseurl</command> must specify the complete URL for
the root directory of the repository, including the
<command>http://</command>, <command>https://</command> or
<command>ftp://</command> prefix. You may also specify a
directory on your system, by using the prefix
<command>file://</command> in the <command>baseurl</command>.
</para>
<tip>
<title>Logging in to Protected Repositories</title>
<para>
To use a password-protected repository, include the correct
username and password in the <command>baseurl</command>. For
example,
<wordasword>ftp://user:password@myrepository.com/$releasever/mypackages/</wordasword>.
</para>
</tip>
<para>
If possible, list more than one directory or server that holds a
copy of the repository. This enables <command>yum</command> to
use another repository if the first is unavailable. By default
<command>yum</command> randomly selects repositories from the
<command>baseurl</command> list. To force <command>yum</command>
to use them in sequence, add the option
<command>failovermethod=priority</command>.
</para>
<para>
It is also good practice to use variables like
<command>$releasever</command> in the URL, rather than setting
these to a specific value. The available variables are listed on
the <command>man</command> page for
<filename>yum.conf</filename>. Using variables enables the same
definition to function when your system is upgraded to a later
version, or if the configuration is copied to another machine.
</para>
<para>
A definition file is shown below that uses all of these
features. In this example, copies of the repository are held in
the directory
<filename>/srv/software/&FED;/&FCVER;/mypackages/</filename> on
the system itself, in the directory
<filename>software/&FED;/&FCVER;/mypackages/</filename> on the
Web server <wordasword>www.my-repository.com/</wordasword>, and
in the directory
<filename>pub/software/&FED;/&FCVER;/mypackages/</filename> on
the FTP server
<wordasword>server.another-repository.org</wordasword>. Here,
<command>yum</command> will access the FTP server with the
username <command>yum-user</command> and the password
<command>qwerty</command>. The <command>failovermethod</command>
ensures that <command>yum</command> will check the copy on the
local machine, before trying the servers in sequence.
</para>
<example id="yum-repo-multidir-example">
<title>A <command>yum</command> Repository Definition File with Failover</title>
<programlisting>
<![CDATA[
[MyPackages]
name=Some packages for Fedora $releasever
baseurl=file:///srv/software/fedora/$releasever/mypackages/
http://www.my-repository.com/software/fedora/$releasever/mypackages/
ftp://yum-user:qwerty@anotherserver.another-repository.org/pub/software/fedora/$releasever/mypackages/
failovermethod=priority
enable=1
gpgcheck=1
]]>
</programlisting>
</example>
<para>
To use a list of servers, substitute
<command>mirrorlist</command> for <command>baseurl</command>.
</para>
<para>
Set <command>gpgcheck=0</command> if it is necessary to disable
signature checking for the packages provided by this repository.
Avoid distributing or installing unsigned packages.
</para>
</section>
<section id="sn-updating-repository">
<title>Updating a Repository</title>
<indexterm>
<primary>repositories, updating</primary>
</indexterm>
<para>
Whenever a package is added, or replaced with a different
version, you must run <command>createrepo</command> again for
the index files to be updated. If you are mirroring an existing
repository then you may assume that the site administrator
updates the indexes, but for safety you should add this to your
synchronization scripts. The <command>createrepo</command>
utility can be run as frequently as you wish.
</para>
</section>
</section>
<section id="sn-yum-proxy-server">
<title>Using <command>yum</command> with a Proxy Server</title>
<indexterm>
<primary>proxy server, with yum</primary>
</indexterm>
<indexterm>
<primary>yum, using a proxy server</primary>
</indexterm>
<para>
Repositories may be accessed through standard proxy servers. If
your system is connected to the Internet through a Web proxy
server, specify the details of the server in
<filename>/etc/yum.conf</filename>. The <command>proxy</command>
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
<command>proxy_username</command> and
<command>proxy_password</command> settings.
</para>
<para>
For example, the settings below enable <command>yum</command> to
use the proxy server <command>mycache.mydomain.com</command>,
connecting to port <command>3128</command>, with the username
<command>yum-user</command> and the password
<command>qwerty</command>.
</para>
<example id="config-file-httpproxy">
<title>Configuration File Settings for Using A Proxy Server</title>
<programlisting>
<![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
]]>
</programlisting>
</example>
<note>
<title>Global Settings</title>
<para>
Defining a proxy server in <filename>/etc/yum.conf</filename>
means that <emphasis>all</emphasis> users connect to the proxy
server with those details when using <command>yum</command>.
</para>
</note>
<para>
To enable proxy access for a specific user, add the lines in the
example box below to their 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
<command>mycache.mydomain.com</command>, connecting to port
<command>3128</command>.
</para>
<example id="profile-script-httpproxy">
<title>Profile Settings for Using a Proxy Server</title>
<programlisting>
<![CDATA[
# The Web proxy server used by this account
http_proxy="http://mycache.mydomain.com:3128"
export http_proxy
]]>
</programlisting>
</example>
<para>
If the proxy server requires a username and password then add
these to the URL. For example, to include the username
<command>yum-user</command> and the password
<command>qwerty</command>:
</para>
<example id="profile-script-httpproxy-withpassword">
<title>Profile Settings for a Secured Proxy Server</title>
<programlisting>
<![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
]]>
</programlisting>
</example>
<note>
<title><command>http_proxy</command> Variable with Other Utilities</title>
<para>
The <command>http_proxy</command> 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>
<index id="generated-index"></index>
</article>
More information about the Fedora-docs-commits
mailing list