Author: pfrields
Update of /cvs/docs/mirror-tutorial In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv11455
Modified Files: mirror-tutorial-en.xml Log Message: Rolled in newest mirror-tutorial (#163912)
Index: mirror-tutorial-en.xml =================================================================== RCS file: /cvs/docs/mirror-tutorial/mirror-tutorial-en.xml,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- mirror-tutorial-en.xml 22 Jul 2005 11:39:45 -0000 1.5 +++ mirror-tutorial-en.xml 22 Jul 2005 12:34:43 -0000 1.6 @@ -1,11 +1,11 @@ - <!-- $Id: --> +<!-- $Id: --> <!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"> +<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../common/fedora-entities-en.xml"> %FEDORA-ENTITIES-EN;
-<!ENTITY BOOKID "mirror-tutorial-0.24 (2005-07-22)"> <!-- change version of manual and date here --> +<!ENTITY BOOKID "mirror-tutorial-0.27 (2004-12-01)"> <!-- change version of manual and date here -->
]>
@@ -78,12 +78,51 @@ </revision> <revision> <revnumber>0.24</revnumber> - <date>2005-07-22</date> + <date>2004-09-09</date> <authorinitials>PaulWFrields</authorinitials> <revdescription> <para> - Removed references to <command>yum-arch</command> and replaced with - <command>createrepo</command>. + Brought introduction section in line with &FDP; standards. + </para> + </revdescription> + </revision> + <revision> + <revnumber>0.25</revnumber> + <date>2004-10-13</date> + <authorinitials>PaulWFrields</authorinitials> + <revdescription> + <para> + Incorporated all suggested changes by KWade. + </para> + </revdescription> + </revision> + <revision> + <revnumber>0.26</revnumber> + <date>2004-12-01</date> + <authorinitials>PaulWFrields</authorinitials> + <revdescription> + <para> + Updated repository setup to include createrepo. + </para> + </revdescription> + </revision> + <revision> + <revnumber>0.27</revnumber> + <date>2004-12-01</date> + <authorinitials>PaulWFrields</authorinitials> + <revdescription> + <para> + Minor corrections. + </para> + </revdescription> + </revision> + <revision> + <revnumber>0.28</revnumber> + <date>2005-01-30</date> + <authorinitials>PaulWFrields</authorinitials> + <revdescription> + <para> + Minor corrections. </para> </revdescription> </revision> @@ -95,19 +134,19 @@ <section id="sn-purpose"> <title>Purpose</title> <para> - This tutorial presents a number of related topics that allow an - administrator to seamlessly integrate mirroring and update services for - &FC;. These services are used to provision a classroom, laboratory, or - office. These service provisions also increase ease of use and enhance - user experience, adding to the perceived value of non-proprietary - operating systems and software. + This tutorial presents a number of related topics that allow an + administrator to seamlessly integrate mirroring and update services for + &FC;. You can use these services to provision a classroom, laboratory, + or office. These service provisions also increase ease of use and + enhance user experience, adding to the perceived value of + non-proprietary operating systems and software. </para> <note> <title>A note about &FC; and this document</title> <para> This document applies to &FC; &FCVER;, which may not be the newest - release of &FC;. Find more information about the newest version at - &FP-URL;. + release of &FC;. You can find more information about the newest + version at &FP-URL;. </para> </note> </section> @@ -151,11 +190,13 @@ <para> The site from which you retrieve files to build your mirror is called an <emphasis>upstream mirror</emphasis><indexterm> - <primary>mirror</primary> <secondary>upstream</secondary> + <primary>mirror</primary> <secondary>upstream</secondary> </indexterm>. If possible, choose an upstream mirror that is located close to you geographically. This reduces unnecessary traffic across transcontinental sections of the Internet, where bandwidth is limited - and expensive. + and expensive. Use only upstream mirrors that are intended for public + access, unless you have permission from the upstream mirror site + administrator. </para> </section> <section id="sn-additional-resources"> @@ -164,11 +205,11 @@ For more information on installing &FC; see the &FC; &IG;<!-- at &IG-URL; -->. For more information on basic Internet protocols, see <ulink - url="http://library.albany.edu/internet/internet.html%22%3Ehttp://library.albany....</ulink>, + url="http://library.albany.edu/internet/internet.html%22%3Ehttp://library.albany....</ulink>, or search Google at <ulink - url="http://www.google.com/%22%3Ehttp://www.google.com/</ulink>. For more + url="http://www.google.com/%22%3Ehttp://www.google.com/</ulink>. For more general information about mirrors, see <ulink - url="http://en.wikipedia.org/wiki/Mirror_(computing)%22%3Ehttp://en.wikipedia.org...)</ulink>. + url="http://en.wikipedia.org/wiki/Mirror_(computing)%22%3Ehttp://en.wikipedia.org...)</ulink>. </para> </section> <section id="sn-acknowledgements"> @@ -179,45 +220,23 @@ </para> </section> </section> - + <section id="sn-planning-and-setup"> <title>Planning and Setup</title> - - <!-- I see you removed the following to <para>s in an edit, was this --> - <!-- intentional? --> - - <para> - A <firstterm>mirror</firstterm> - <indexterm><primary>mirror</primary></indexterm> is a server that provides - a copy of one or more collections of files. Mirroring a site reduces - traffic to the original source site, thus spreading the stress and - bandwidth costs of many users across many sites. Side benefits of running - a local mirror include very fast access through the local network, - providing custom services to local users, and increasing your skills in - managing Internet services. - </para> - <para> - The <firstterm>upstream mirror</firstterm><indexterm> - <primary>mirror</primary> - <secondary>upstream</secondary> </indexterm> is the site you retrieve - files from to build your mirror. If possible, choose an upstream mirror - that is located close to you geographically. This reduces unnecessary - traffic across transcontinental sections of the Internet, where bandwidth - is limited and expensive. - </para> - + <section id="sn-hierarchy"> <title>The Distribution Structure</title> <para> - The &FED; <firstterm>distribution</firstterm><indexterm> + The &FED; <emphasis>distribution</emphasis><indexterm> <primary>distribution</primary> </indexterm>, which is the collection of all &FED;-related files, uses the directory tree in <xref linkend="ex-fedora-dir-tree"/>. It may - include multiple versions of &FC;. The tree design makes trimming of + include multiple versions of &FC;. The tree design makes "trimming" of unnecessary or undesired files easier. When setting up a mirror, duplicate this tree exactly, or as closely as possible. Doing so makes automating nightly updates easier. </para> + <example id="ex-fedora-dir-tree"> <title>Fedora directory tree</title> <screen> @@ -257,6 +276,7 @@ +-- x86_64</computeroutput> </screen> </example> + <note> <title>Naming conventions</title> <para> @@ -322,7 +342,7 @@ Installation Disc 1 into the <filename>fedora/linux/core/&FCVER;/<replaceable>arch</replaceable>/os</filename> folder. Then copy all files from the <filename>&FED;</filename> folder - of each of the remaining installation discs into the + of each of the remaining Installation discs into the <filename>fedora/linux/core/&FCVER;/<replaceable>arch</replaceable>/os/&FED;</filename> folder on the server. </para> @@ -395,22 +415,22 @@ </para> <variablelist> <varlistentry> - <term>Older versions of &FC; (any numbered directory).</term> + <term>Older versions of &FC; (any numbered directory).</term> <listitem> <para> - Before you exclude an old version, ensure this does not adversely - affect any of your users. These adverse affects can come in many - forms. For example, the level of support for certain hardware - sometimes changes between releases of &FC;. Users who cannot - install a previous version may not be able to use &FC;. Your users - might need to perform software-related tasks such as building - packages for different &FC; releases. Always remain aware of the - needs of your users during the planning stage. + Before you exclude an old version, ensure + this does not adversely affect any of your users. These adverse + affects can come in many forms. For example, the level of support + for certain hardware sometimes changes between releases of &FC;. + Users who cannot install a previous version may not be able to use + &FC;. Your users might need to perform software-related tasks such + as building packages for different &FC; releases. Always remain + aware of the needs of your users during the planning stage. </para> </listitem> </varlistentry> <varlistentry> - <term>Folders for architectures your site does not support.</term> + <term>Folders for architectures your site does not support.</term> <listitem> <para> If you do not have any x86-64 hosts to support, trimming these @@ -422,16 +442,16 @@ </varlistentry> <varlistentry> <term>The <filename>development</filename> folder (formerly - <filename>rawhide</filename>).</term> + <quote>Rawhide</quote>).</term> <listitem> <para> - This folder contains all the latest bleeding-edge packages from - the &FP;. If you participate in active &FED; development, you - should not trim this branch. &FED; development moves at a rapid - pace and requires frequent updates to the latest development - package versions. However, the frequent updates cause your mirror - to download significant amounts of material during the regular - update cycle. + This folder contains all the latest <quote>bleeding-edge</quote> + packages from the &FP;. If you participate in active &FED; + development, you should not trim this branch. &FED; development + moves at a rapid pace and requires frequent updates to the latest + development package versions. However, the frequent updates cause + your mirror to download significant amounts of material during the + regular update cycle. </para> </listitem> </varlistentry> @@ -441,9 +461,9 @@ <para> These branches contain updates that are being subjected to quality assurance through public testing, as well as the test or - <firstterm>pre-release</firstterm> versions of the &FC; - distribution. The <filename>testing</filename> folder under the - main <filename>core</filename> tree is where test versions of the + <quote>pre-release</quote> versions of the &FC; distribution. The + <filename>testing</filename> folder under the main + <filename>core</filename> tree is where test versions of the distribution, such as &FC; &FCTESTVER;, are kept. (Users of &FC; test distributions are often directed to use the <filename>development</filename> branch to update packages.) The @@ -454,21 +474,16 @@ </listitem> </varlistentry> <varlistentry> - <term>The <filename>debug</filename> folders.</term> + <term>The <filename>debug</filename> folders.</term> <listitem> <para> These folders contain packages that enable developers and skilled users to interpret data created when a program crashes or encounters a bug. If you participate actively in &FED; development, you should not trim these folders. If you trim this - branch, you may still download individual packages on an ad hoc - basis from a nearby public mirror site. <!-- removed - <foreignphrase> mainly because the stylesheet italicized it, yet - the term is neither new nor noteworthy enough to make it stand out - like that ... the usage is correct and may not even be overboard, - but the format outcome is jarring for the reader, and I'd prefer - not to have to hack the XSL to make this bigger. Maybe next time? - --> + branch, you may still download individual packages on an + <foreignphrase>ad hoc</foreignphrase> basis from a nearby public + mirror site. </para> </listitem> </varlistentry> @@ -479,7 +494,8 @@ <para> These folders contain the original source for all the binary RPM packages in the distribution. You may download these packages on - an ad hoc basis if you need to save space on your local mirror. + an <foreignphrase>ad hoc</foreignphrase> basis if you need to save + space on your local mirror. </para> </listitem> </varlistentry> @@ -526,26 +542,26 @@ <itemizedlist> <listitem> <para> - <option>--mirror</option> turns on recursion (descends into all + <command>--mirror</command> turns on recursion (descends into all subdirectories), and duplicates file timestamps; </para> </listitem> <listitem> <para> - <option>-np</option> prevents <command>wget</command> from + <command>-np</command> prevents <command>wget</command> from ascending into the parent directory; </para> </listitem> <listitem> <para> - <option>-nH</option> prevents <command>wget</command> from + <command>-nH</command> prevents <command>wget</command> from writing a directory named after the host (in this case, <filename><replaceable>mirror.example.com</replaceable></filename>); </para> </listitem> <listitem> <para> - <option>--cut-dirs=<replaceable>n</replaceable></option> + <command>--cut-dirs=<replaceable>n</replaceable></command> truncates the first <replaceable>n</replaceable> directories in the path. In the example above, <command>--cut-dirs=2</command> prevents <command>wget</command> from writing the @@ -576,11 +592,10 @@ </para> <para> Begin by identifying the modules available on the upstream mirror site - you have chosen. Note that the double colon - <computeroutput>::</computeroutput> is always used after the host name - to separate it from the rest of the <command>rsync</command> path. The - following command generates a list of <firstterm>modules</firstterm> - on the upstream mirror. + you have chosen. Note that the double colon <quote>::</quote> is + always used after the host name to separate it from the rest of the + <command>rsync</command> path. The following command generates a list + of <quote>modules</quote> on the upstream mirror. </para>
<screen> @@ -595,10 +610,9 @@ equivalent to the <filename>fedora/linux/core</filename> path found at the &FP; main download server. To list the contents of the &FC; &FCVER; distribution folder on the upstream server, issue the - following command. Do not forget the trailing slash - <computeroutput>/</computeroutput>. Without it, you only receive a - listing of a folder name that matches the last component of the remote - path. + following command. Do not forget the trailing slash <quote>/</quote>. + Without it, you only receive a listing of a folder name that matches + the last component of the remote path. </para>
<screen> @@ -614,8 +628,8 @@ your system to the end of the command line. The resulting tree of files from the listing you perform are downloaded to the local path you specify. Remember, if you leave off the trailing slash on the - remote path, then the last component of that path is created as a new - folder inside the target directory, and its contents are copied. + remote path, then the last component of that path is created as a + folder, and its contents are copied. </para>
<screen> @@ -625,7 +639,7 @@ <para> When downloading using <command>rsync</command> for mirror purposes, use some of the command line switches to improve performance and - feedback. The switches <option>-PHav</option> enable the following + feedback. The switches <command>-PHav</command> enable the following <command>rsync</command> features: </para> <itemizedlist> @@ -669,6 +683,7 @@ understand the consequences. </para> </caution> + <screen> <userinput>rsync -PHav mirror.example.org::fedora-linux-core/&FCVER;/ /var/ftp/pub/mirror/fedora/core/&FCVER;</userinput> </screen> @@ -738,7 +753,7 @@ Use the <command>--exclude</command> switch, along with a simple pattern, to disallow download of certain files and/or folders. For instance, <command>--exclude "*.iso"</command> excludes the download - of any file that has the string <quote>x86_64</quote> in its filename. + of any file whose name ends with the string ".iso". </para> <para> Use the <command>--delete</command> switch, again with a pattern, to @@ -1058,40 +1073,105 @@
<para> To set up a <command>yum</command> repository, you must write a - directory of header information from which the clients extract the data that - they require. The directory is named <filename>repodata/</filename>. It is - created by using the command <command>createrepo</command>, which is run - against the directory <emphasis>under which</emphasis> you want the - <filename>repodata/</filename> directory to appear. The - <command>createrepo</command> program searches recursively through that - directory and any subdirectories for RPM packages, and includes them in - the header data. + directory that contains information which the clients require to resolve + RPM dependencies. The directory's name depends on the version of + <command>yum</command> it supports. It is permissible to have both kinds + of repository information in a single repository. </para>
+ <section id="sn-yum-arch"> + <title><command>yum-arch</command></title> + <para> + A directory which supports older versions of <command>yum</command> is + named <filename>headers</filename>. It is created by using the command + <command>yum-arch</command>, which is run against the directory + <emphasis>under which</emphasis> you want the + <filename>headers</filename> directory to appear. The + <command>yum-arch</command> program searches recursively through that + directory and any subdirectories for RPM packages, and includes them + in the header data. + </para> + +<screen> +<userinput>yum-arch -l -s /var/ftp/pub/linux/fedora/core/&FCVER;/i386/os</userinput> +</screen> + + <para> + The <command>-l</command> switch follows symbolic links. The + <command>-s</command> switch includes SRPMS (source RPM packages) in + the header list. The command above creates the <command>yum</command> + header cache in the directory + <filename>/var/ftp/pub/linux/fedora/core/&FCVER;/i386/os/headers</filename>. + </para> + </section> + + <section id="sn-createrepo"> + <title><command>createrepo</command></title> + <para> + The <command>createrepo</command> command creates repository + information to support newer versions of <command>yum</command> (and + possibly other repository client programs). The + <command>createrepo</command> command stores this data in a folder + named <filename>repodata</filename>. Just as with + <command>yum-arch</command>, run <command>createrepo</command> against + the directory <emphasis>under which</emphasis> you want the + <filename>repodata</filename> directory to appear. The + <command>createrepo</command> program also searches recursively for + RPM packages to include in the repository data. + </para> + <screen> <userinput>createrepo /var/ftp/pub/linux/fedora/core/&FCVER;/i386/os</userinput> </screen>
- <para> - The command above creates the <command>yum</command> header cache in the directory - <filename>/var/ftp/pub/linux/fedora/core/&FCVER;/i386/os/headers</filename>. - Typically <command>createrepo</command> is run against at least the - following locations: - </para> - <itemizedlist> - <listitem> - <para> - The stock distribution; for example, - <filename>/var/ftp/pub/linux/fedora/core/&FCVER;/i386/os/</filename>. - </para> - </listitem> - <listitem> + <para> + The command above creates the repository data in the directory + <filename>/var/ftp/pub/linux/fedora/core/&FCVER;/i386/os/repodata</filename>. + </para> + <important> + <title>Supporting &FC; 3 and beyond</title> <para> - Official updates to the distribution; for example, - <filename>/var/ftp/pub/linux/fedora/core/updates/&FCVER;/</filename>. + &FC; 3 ships with a newer version of <command>yum</command>. To + support &FC; 3 <command>yum</command> clients, you + <emphasis>must</emphasis> use <command>createrepo</command> on your + server's repositories. </para> - </listitem> - </itemizedlist> + </important> + <para> + You may not be able to foresee all the possible uses for your server's + repositories. To minimize problems for your clients, create both kinds + of repository data for any repositories. + </para> + + </section> + + <section id="sn-repository-locations"> + <title>Repository Locations</title> + <para> + Typically <command>yum-arch</command> or <command>createrepo</command> + is run against at least the following locations: + </para> + <itemizedlist> + <listitem> + <para> + The stock distribution; for example, + <filename>/var/ftp/pub/linux/fedora/core/&FCVER;/i386/os/</filename>. + For <command>yum-arch</command> use the <command>-l</command> and + <command>-s</command> options to follow the linked directory + <filename>SRPMS</filename> and include the source packages + therein. + </para> + </listitem> + <listitem> + <para> + Official updates to the distribution; for example, + <filename>/var/ftp/pub/linux/fedora/core/updates/&FCVER;/</filename>. + Once again, for <command>yum-arch</command> use + <command>-l</command> and/or <command>-s</command> if appropriate. + </para> + </listitem> + </itemizedlist> + </section>
</section>
@@ -1473,18 +1553,16 @@ </screen>
<para> - If a user forgets the <command>--aid</command> switch, they - still receive hints. Normally <command>rpm</command> - displays a slightly cryptic list of capability requirements, - instead of straightforward package names. If you edit - <filename>/etc/rpm/macros.solve</filename> as shown, - <command>rpm</command> displays a list of required package + If a user forgets the <command>--aid</command> switch, they still + receive hints. Normally <command>rpm</command> displays a slightly + cryptic list of capability requirements, instead of straightforward + package names. If you edit <filename>/etc/rpm/macros.solve</filename> + as shown, <command>rpm</command> displays a list of required package names instead. </para> <para> - Package dependency solutions using <command>--aid</command> - are also restricted as shown above in <xref - linkend="tp-s-c-p-stock-only"/>. + Package dependency solutions using <command>--aid</command> are also + restricted as shown above in <xref linkend="tp-s-c-p-stock-only"/>. </para>
</section> @@ -1503,51 +1581,46 @@ <section id="sn-up2date-config"> <title><filename>/etc/sysconfig/rhn/up2date</filename></title> <para> - The <filename>/etc/sysconfig/rhn/up2date</filename> file - controls the global configuration of the - <application>up2date</application> application. This file is - well commented and is not explained in great detail - here. Here are some points to keep in mind, however: + The <filename>/etc/sysconfig/rhn/up2date</filename> file controls the + global configuration of the <application>up2date</application> + application. This file is well commented and is not explained in great + detail here. Here are some points to keep in mind, however: </para> <itemizedlist> <listitem> <para> By default, the user must intervene to update <command>kernel</command> packages. See the - <command>pkgSkipList</command> variable. At the command - line, use the <command>-f</command> option to force an - override. At the GUI interface, - <application>up2date</application> allows the user to + <command>pkgSkipList</command> variable. At the command line, use + the <command>-f</command> option to force an override. At the GUI + interface, <application>up2date</application> allows the user to override. </para> </listitem> <listitem> <para> - By default, <command>up2date</command> does not remove - old <command>kernel</command> packages. See the + By default, <command>up2date</command> does not remove old + <command>kernel</command> packages. See the <command>pkgsToInstallNotUpdate</command> variable. When - <command>up2date</command> installs a new kernel - package, the old version remains in place until removed - explicitly. + <command>up2date</command> installs a new kernel package, the old + version remains in place until removed explicitly. </para> </listitem> <listitem> <para> - The configuration file also allows use of an HTTP proxy - if desired. A number of variables pertain to this - function. + The configuration file also allows use of an HTTP proxy if + desired. A number of variables pertain to this function. </para> </listitem> <listitem> <para> - By default, <application>up2date</application> sends - mail to <email>root@localhost</email> when packages are - updated in batch mode. (Running <command>up2date - -u</command> starts <application>up2date</application> - in batch mode.) See the <command>adminAddress</command> - option. If you support multiple clients and intend to - use batch mode at your site, you should set a new - address here. + By default, <application>up2date</application> sends mail to + <email>root@localhost</email> when packages are updated in batch + mode. (Running <command>up2date -u</command> starts + <application>up2date</application> in batch mode.) See the + <command>adminAddress</command> option. If you support multiple + clients and intend to use batch mode at your site, you should set + a new address here. </para> </listitem> </itemizedlist> @@ -1592,7 +1665,7 @@ Edit <filename>/etc/sysconfig/rhn/sources</filename> for the clients at your site to point to your repository. For any repository, point to the URL for the directory containing the <filename>headers</filename> - folder. You created this folder using <command>createrepo</command> in + folder. You created this folder using <command>yum-arch</command> in <xref linkend="sn-repositories"/>. You will likely have two repositories, one for the stock distribution and one for updates. Examples are shown below; you may wish to point to an internal address @@ -1601,8 +1674,8 @@ </para>
<screen> -<userinput>yum fedora-core-2 http://www.mydomain.org/pub/linux/fedora/core/2/i386/os -yum fc2-updates http://www.mydomain.org/pub/linux/fedora/core/updates/2/i386</userinput> +<userinput>yum fedora-core-&FCVER; http://www.mydomain.org/pub/linux/fedora/core/&FCVER;/i386/os +yum fc&FCVER;-updates http://www.mydomain.org/pub/linux/fedora/core/updates/&FCVER;/i386</userinput> </screen>
</section> @@ -1611,7 +1684,7 @@
</section>
-<!-- +<!--
FIXME:
@@ -1634,9 +1707,3 @@ </index>
</article> - -<!-- -Local variables: -mode: xml -End: --->