[software-management-guide/fc3] add old version of main XML file
Rüdiger Landmann
rlandmann at fedoraproject.org
Sun Jun 6 14:53:13 UTC 2010
commit 839998b87a75da5a4e773b843d219d4f58ebf96d
Author: Ruediger Landmann <r.landmann at redhat.com>
Date: Mon Jun 7 00:52:36 2010 +1000
add old version of main XML file
yum-software-management-en-2005-07-17.xml | 1517 +++++++++++++++++++++++++++++
1 files changed, 1517 insertions(+), 0 deletions(-)
---
diff --git a/yum-software-management-en-2005-07-17.xml b/yum-software-management-en-2005-07-17.xml
new file mode 100644
index 0000000..83397b6
--- /dev/null
+++ b/yum-software-management-en-2005-07-17.xml
@@ -0,0 +1,1517 @@
+<!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.5.0 (2005-07-09)"> <!-- 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 "4">
+<!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-purpose">
+ <title>Purpose</title>
+
+ <para>
+ This tutorial presents basic concepts of software management on
+ &FED; systems. It outlines the major functions of
+ <command>yum</command>, the recommended software management tool
+ for &FED;.
+ </para>
+ </section>
+
+ <section id="sn-software-management-audience">
+ <title>Audience</title>
+
+ <para>
+ This tutorial is intended for &FED; users of all experience
+ levels.
+ </para>
+
+ </section>
+
+ <section id="sn-software-management-usingdoc">
+ <title>Using This Document</title>
+
+ <para>
+ 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, read
+ <xref linkend="sn-software-management-concepts"/> before using
+ <command>yum</command> for the first time. If you are an
+ experienced Linux user, start with <xref
+ linkend="sn-updating-your-system"/>.
+ </para>
+
+ <para>
+ If you have several &FED; systems on a network, you may benefit
+ from setting up your own software repositories to manage the
+ process of installation and updates. Refer to
+ <xref linkend="sn-managing-repositories"/> for details of
+ maintaining your own repositories.
+ </para>
+
+ <para>
+ Most of the examples in this document use the package
+ <filename>tsclient</filename>, which is included with &FC;. The
+ <filename>tsclient</filename> package provides an application
+ for remote desktop access. If you install it 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. Any commands in this tutorial which
+ require root access will prompt you for the root password. The
+ procedures use the command <command>su
+ <option>-c</option></command> to provide this facility.
+ </para>
+ </important>
+ </section>
+
+ <section id="sn-yum-additional-resources">
+ <title>Additional Resources</title>
+ <indexterm>
+ <primary>yum</primary>
+ <secondary>documentation</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>yum</primary>
+ <secondary>man pages</secondary>
+ </indexterm>
+ <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, using the
+ following commands:
+ </para>
+
+ <screen>
+ <userinput>man yum man yum.conf</userinput>
+ </screen>
+
+ <remark role="fixme">If you want to use a para for the next bit,
+ use sentences and graft them together. Otherwise, you can use a
+ variablelist, or an itemizedlist. [PWF]</remark>
+
+ <indexterm>
+ <primary>yum</primary>
+ <secondary>home page</secondary>
+ </indexterm>
+ <para>
+ The official home page for <command>yum</command> on the World
+ Wide Web is <ulink url="http://linux.duke.edu/projects/yum/"/>.
+ <indexterm>
+ <primary>yum</primary>
+ <secondary>mailing lists</secondary>
+ </indexterm> The official mailing list for
+ <command>yum</command> users is at <ulink
+ url="https://lists.dulug.duke.edu/mailman/listinfo/yum/"/>.
+ The archive for the <command>yum</command> development mailing
+ list is at <ulink
+ url="https://lists.dulug.duke.edu/pipermail/yum-devel/"/>.
+ </para>
+ </section>
+ </section>
+
+ <section id="sn-software-management-concepts">
+ <title>Software Management Concepts</title>
+
+ <section id="sn-about-packages">
+ <title>About Packages</title>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <para>
+ &FED; software and documentation is supplied in the form of RPM
+ <firstterm>packages</firstterm>. Each package is a compressed
+ archive which contains 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 &FED; installation process
+ uses the packages supplied with &FC; 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 with
+ a GPG <firstterm>public key</firstterm>. The
+ <command>yum</command> and <command>rpm</command> utilities
+ share a common <firstterm>keyring</firstterm> which stores all
+ public keys for the package sources approved by the system
+ administrator.
+ </para>
+ </section>
+
+ <section id="sn-about-repositories">
+ <title>About Repositories</title>
+ <indexterm>
+ <primary>repositories</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <para>
+ A <firstterm>repository</firstterm> is a directory which
+ contains prepared files which refer to software packages.
+ Software management utilities such as <command>yum</command>
+ automatically locate and obtain the correct RPM packages for an
+ application from these <firstterm>repositories</firstterm>. 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 your system's software, or search for new software by
+ specifying criteria. In each case, the management utility
+ connects to the configured repositories and checks files in each
+ one to find the correct packages.
+ </para>
+
+ <para>
+ If you use repositories, you always receive the current version
+ of the software. If several versions of the same package are
+ available, your management utility automatically selects the
+ latest version.
+ </para>
+
+ <para>
+ For these reasons, you should only manually install software
+ when you are confident that no repository can currently provide
+ it. If a piece of installed software is not available from a
+ repository, you cannot automatically find or install newer
+ versions. You must keep that product updated manually.
+ </para>
+
+ <para>
+ The package management utilities in &FC; are automatically
+ configured to use the network of repository servers maintained
+ by the &FP;. These repositories contain 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>
+
+ <remark role="fixme">Use the terminology from the &FP; web site.
+ Personally, I have no quibble with "free" vs. "open source"
+ software, but rule #1 is to be consistent across the whole
+ project. Since the web site says "open source," let's use
+ that. [PWF]</remark>
+
+ <note>
+ <title>Open Source Software</title>
+
+ <para>
+ All of the software provided by the &FP; is open source
+ software. For more information about open source software,
+ refer to <ulink url="http://www.opensource.org/"/>.
+ </para>
+ </note>
+ </section>
+
+ <section id="sn-about-dependencies">
+ <title>About Dependencies</title>
+ <indexterm>
+ <primary>dependencies</primary>
+ <secondary>defined</secondary>
+ </indexterm>
+ <para>
+ You must consider package <firstterm>dependencies</firstterm>
+ when manually installing software. For RPM software, a
+ dependency is a capability provided by one package on which
+ other packages rely. Some programs rely on external shared
+ <firstterm>libraries</firstterm> to run properly. If a library
+ is provided by an external package, that package may be a
+ dependency for numerous other packages.
+ </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
+ <command>yum</command> utility installs all required packages
+ which are not already present on your system. If a new
+ application has requirements that conflict with existing
+ software, <command>yum</command> aborts without making any
+ changes to your system.
+ </para>
+ </section>
+
+ <section id="sn-package-names">
+ <title>Understanding Package Names</title>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>hardware compatibility</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>naming</secondary>
+ </indexterm>
+ <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 only the name of the package itself with
+ <command>yum</command>, except when it is necessary to specify
+ the exact version or type. <remark role="fixme">When exactly is
+ that necessary? Make this clear. [PWF]</remark> To specify the exact
+ version of the application, use
+ <filename>name-version</filename>. The package listings provided
+ by <command>yum</command> use the format
+ <filename>name.architecture</filename>, to specify the type of
+ computer for which the package is intended.
+ </para>
+
+ <para>
+ These properties 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 architecture <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 architecture <option>noarch</option> have no architecture
+ requirement.
+ </para>
+
+ <para>
+ Some software can be optimized for particular types of
+ Intel-compatible machine, and separate packages may be 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 CPU is an
+ <option>i586</option>. Computers with an Intel Pentium II or
+ later, 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>
+ <indexterm>
+ <primary>Add/Remove Applications utility</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Alert Icon</primary>
+ </indexterm>
+ <indexterm>
+ <primary>up2date</primary>
+ </indexterm>
+ <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 <application>Alert Icon</application> that
+ keeps you informed about package updates. Until your system is
+ updated, the icon appears as a red circle with a flashing
+ exclamation mark. The <application>Alert Icon</application> is
+ integrated with <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>, for consistency
+ you should also configure <application>up2date</application> to
+ use them.
+ </para>
+
+ <note>
+ <title>Repository Configuration</title>
+ <para>
+ In &FC; 4 and beyond, <application>up2date</application> is
+ configured to automatically use repositories configured for
+ <command>yum</command>. If you configure any new repositories
+ for <command>yum</command>, <application>up2date</application>
+ will use them also.
+ </para>
+ </note>
+
+ <para>
+ Also included in &FC; is
+ <application>system-config-packages</application>. To run this
+ utility, rom the <guilabel>Main Menu</guilabel>, select
+ <menuchoice><guimenu>System
+ Settings</guimenu><guimenuitem>Add/Remove
+ Applications</guimenuitem></menuchoice>. Unlike
+ <application>up2date</application> and <command>yum</command>,
+ this utility installs software packages from your &FC;
+ installation discs, and does not use repositories. This
+ application is used on 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. The
+ <command>rpm</command> command can also be used to manually
+ install and remove packages from your system. Installing software
+ with the <command>rpm</command> utility can be difficult for
+ novices, 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-updating-your-system">
+ <title>Updating Your System with <command>yum</command></title>
+ <indexterm>
+ <primary>updating</primary>
+ <secondary>full system</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>yum</primary>
+ <secondary>updating full system</secondary>
+ </indexterm>
+
+ <remark role="fixme">Your original paragraph below was: "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." Remember this should be a procedural tutorial, so focus
+ on telling the user what to do. In technical docs "To ABC, do XYZ"
+ is much more effective than "You may do XYZ if you want to ABC."
+ It's also easier to translate, and keeps you from slipping into
+ passive voice. [PWF]</remark>
+
+ <para>
+ To update all of your &FED; system's software in a single
+ operation, select <menuchoice>
+ <guimenu>Applications</guimenu>
+ <guisubmenu>System Tools</guisubmenu>
+ <guimenuitem>Terminal</guimenuitem>
+ </menuchoice> and type:
+ </para>
+<screen>
+<userinput>su -c 'yum update'</userinput>
+</screen>
+ <para>
+ Enter the password for the <systemitem
+ class="username">root</systemitem> account when prompted.
+ </para>
+
+<!-- MARKER - LAST EDITS - PWF -->
+<!-- start worrying about passive voice below! -->
+
+ <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>
+ <indexterm>
+ <primary>automatic updating</primary>
+ </indexterm>
+ <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>
+ <indexterm>
+ <primary>packages, locating</primary>
+ </indexterm>
+ <indexterm>
+ <primary>searching for packages</primary>
+ </indexterm>
+ <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 with <command>yum</command></title>
+ <indexterm>
+ <primary>yum, package management</primary>
+ </indexterm>
+ <para>
+ The <command>yum</command> utility has four basic management
+ functions:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>install</option> new software from the repositories.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>update</option> existing software.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>remove</option> unwanted software.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>localinstall</option>, to install software from a
+ individual package.
+ </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-withrepositories">
+ <title>Installing New Software with <command>yum</command></title>
+ <indexterm>
+ <primary>installing software with yum</primary>
+ </indexterm>
+ <indexterm>
+ <primary>software, 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-installing-frompackage">
+ <title>Installing Software from a Package with <command>yum</command></title>
+ <indexterm>
+ <primary>installing software with yum (from a package)</primary>
+ </indexterm>
+ <indexterm>
+ <primary>software, installing from a package</primary>
+ </indexterm>
+ <para>
+ Use the <option>localinstall</option> option to install software
+ from an individual package file on your system. In this mode
+ <command>yum</command> simply installs the specified package
+ without connecting to any repository. You are responsible for
+ ensuring that all of the dependencies are already installed on
+ your system.
+ </para>
+
+ <para>
+ To install the package
+ <filename>tsclient-0.132-4.i386.rpm</filename>, enter the
+ command:
+ </para>
+<screen>
+<userinput>su -c 'yum localinstall <replaceable>tsclient-0.132-4.i386.rpm</replaceable>'</userinput>
+</screen>
+ <para>
+ Enter the root password when prompted.
+ </para>
+
+ <note>
+ <title>Public Key is Required</title>
+
+ <para>
+ You must ensure that the public key for the package source has
+ been imported before installing a package without a
+ repository. Refer to
+ <xref linkend="sn-authorizing-package-sources"/>
+ </para>
+ </note>
+ </section>
+
+ <section id="sn-yum-updating-withrepositories">
+ <title>Updating Software with <command>yum</command></title>
+ <indexterm>
+ <primary>updating software with yum</primary>
+ </indexterm>
+ <indexterm>
+ <primary>software, 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-software">
+ <title>Removing Software with <command>yum</command></title>
+ <indexterm>
+ <primary>removing software with yum</primary>
+ </indexterm>
+ <indexterm>
+ <primary>software, 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>
+ The configuration file for each repository should include the
+ location of the 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-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-authorizing-package-sources">
+ <title>Manually Authorizing Package Sources</title>
+ <indexterm>
+ <primary>public keys, adding</primary>
+ </indexterm>
+ <para>
+ To manually add a public key to your <command>rpm</command>
+ keyring, use the <option>import</option> feature of the
+ <command>rpm</command> utility. For example, to import the file
+ <filename>GPG-PUB-KEY.asc</filename>, type the following:
+ </para>
+<screen>
+<userinput>su -c 'rpm --import <replaceable>GPG-PUB-KEY.asc</replaceable>'</userinput>
+</screen>
+ <para>
+ Enter the root password when prompted.
+ </para>
+
+ <para>
+ You may 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-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 to disable this file, or 1 to enable it)
+ gpgcheck=(0 to disable checking signatures of packages from this repository, or 1 to enable checking)
+ gpgkey=url://path/to/gpg-key-file
+ ]]>
+ </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
+ gpgkey=http://www.my-repository.com/software/fedora/keys/RPM-GPG-KEY.asc
+ ]]>
+ </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>
+
+<!--
+Local variables:
+mode: xml
+fill-column: 72
+End:
+-->
More information about the docs-commits
mailing list