centos-errata.8

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CENTOS-ERRATA 8"
.TH CENTOS-ERRATA 8 "2012-01-18" "centos-errata.py 0.3" "Spacewalk Utilities"
.SH "NAME"
centos\-errata.py
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
centos\-errata.py [options] [filename]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
centos\-errata.py is a tool to \*(L"scrape\*(R" data from the emails to the
\&\f(CW\*(C`centos\-announce\*(C'\fR mailing list and populate Spacewalk with errata
information. Optionally, it can download additional details from
RedHat. 
.PP
The program accepts the following options:
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
show program's version number and exit
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
show this help message and exit
.IP "\fB\-s\fR \fIspacewalk.example.com\fR, \-\-server=\fIspacewalk.example.com\fR" 4
.IX Item "-s spacewalk.example.com, --server=spacewalk.example.com"
Spacewalk server hostname
.IP "\fB\-l\fR \fI\s-1LOGIN\s0\fR, \fB\-\-login\fR=\fI\s-1LOGIN\s0\fR" 4
.IX Item "-l LOGIN, --login=LOGIN"
Spacewalk Login
.IP "\fB\-\-password\fR=\fIpassword\fR" 4
.IX Item "--password=password"
Spacewalk password (cleartext). If you don't specify this option or
the corresponding \fB\s-1CONFIGURATION\s0 \s-1FILE\s0\fR option the tool will prompt
you interactively.
.IP "\fB\-\-max\-errata\fR=\fIN\fR" 4
.IX Item "--max-errata=N"
Maximum number of errata to process at once. Only relevant to format 'mail\-archive.com'
.IP "\fB\-c\fR \fI/path/to/file.cfg\fR, \fB\-\-config\fR=\fI/path/to/file.cfg\fR" 4
.IX Item "-c /path/to/file.cfg, --config=/path/to/file.cfg"
Read the specified config file in addition to the the default \fIcentos\-errata.cfg\fR
.IP "\fB\-f \s-1FORMAT\s0\fR, \fB\-\-format\fR=\fIdigest|archive|mail\-archive.com\fR" 4
.IX Item "-f FORMAT, --format=digest|archive|mail-archive.com"
Select input format for tool. Default is digest. Valid options are \fIdigest\fR, \fIarchive\fR, \fImail\-archive.com\fR
.IP "\fB\-\-scrape\-rhn\fR" 4
.IX Item "--scrape-rhn"
Connect to the RedHat Network site and attempt to download errata information
.IP "\fB\-\-show\-config\fR" 4
.IX Item "--show-config"
Do not connect to the Spacewalk server, just print configuration information
.IP "\fB\-t\fR, \fB\-\-test\fR" 4
.IX Item "-t, --test"
Do not connect to the Spacewalk server, just process the input file and
print errata information. Will also print configuration information
.IP "\fB\-\-centos\-version\fR=\fI\s-1CENTOS_VERSION\s0\fR" 4
.IX Item "--centos-version=CENTOS_VERSION"
The centos version (e.g. '5' for Centos 5.3)
.IP "\fB\-\-search\-strategies\fR=\fI[dir]\fR,\fI[spacewalk]\fR" 4
.IX Item "--search-strategies=[dir],[spacewalk]"
Set place(s) to look for package \s-1NVREA\s0. Allowable search strategies
\&\*(L"spacewalk\*(R" (look in spacewalk) and \*(L"dir\*(R" (look in the package directories). Example: \*(L"dir,spacewalk\*(R" or just \*(L"dir\*(R"
.PP
For each architecture specified in the \fB\s-1CONFIGURATION\s0 \s-1FILE\s0\fR, you will
get the following options:
.IP "\fB\-\-\f(BI\s-1ARCH\s0\fB\-channel\fR=\fIChannel-Name\fR[,\fIChannel-Name\fR,..]" 4
.IX Item "--ARCH-channel=Channel-Name[,Channel-Name,..]"
The updates channel for arch \fI\s-1ARCH\s0\fR
.IP "\fB\-\-\f(BI\s-1ARCH\s0\fB\-packagedir\fR=\fI/path/to/directory\fR" 4
.IX Item "--ARCH-packagedir=/path/to/directory"
The package directory for arch \fI\s-1ARCH\s0\fR
.IP "\fB\-\-\f(BI\s-1ARCH\s0\fB\-ft\-channel\fR=\fIFastTrack-Channel-Name\fR[,\fIFastTrack-Channel-Name\fR,..]" 4
.IX Item "--ARCH-ft-channel=FastTrack-Channel-Name[,FastTrack-Channel-Name,..]"
The FastTrack updates channel for arch \fI\s-1ARCH\s0\fR
.IP "\fB\-\-\f(BI\s-1ARCH\s0\fB\-ft\-packagedir\fR=\fI/path/to/directory\fR" 4
.IX Item "--ARCH-ft-packagedir=/path/to/directory"
The FastTrack package directory for arch \fI\s-1ARCH\s0\fR
.PP
Each option has a conterpart in the \fB\s-1CONFIGURATION\s0 \s-1FILE\s0\fR and usually
you will want to configure most things there. 
.SH "CONFIGURATION FILE"
.IX Header "CONFIGURATION FILE"
The basic structure of the configuration file is a \f(CW\*(C`centos errata\*(C'\fR
section for config options that affect the whole tool, a \f(CW\*(C`spacewalk\*(C'\fR section for server details and an
architecture-specific section for config options that affect a
particular architecture.
.PP
Valid architectures are: i386, x86_64, ia64, ppc, alpha, sparc, s390 and s390(x)
.PP
The \f(CW\*(C`centos errata\*(C'\fR section contains the following options:
.IP "\fBversion\fR" 4
.IX Item "version"
Major release of CentOS you are targeted. E.g. \*(L"5\*(R" for \*(L"CentOS 5.4\*(R"
.IP "\fBrelease\fR" 4
.IX Item "release"
Minor release you are targeting. E.g. \*(L"4\*(R" for \*(L"CentOS 5.4\*(R"
.IP "\fBscrape_rhn\fR" 4
.IX Item "scrape_rhn"
If True, \s-1RHN\s0 is used to populate errata with details. Default: False
.IP "\fBsearch_strategies\fR" 4
.IX Item "search_strategies"
This option controls how the script looks for packages. It is a comma
separated list of values. Valid values are \fIspacewalk\fR and \fIdir\fR. 
.Sp
\&\fIspacewalk\fR searches spacewalk
.Sp
\&\fIdir\fR searches the package directories which must be defined for all
architectures if this option is used. 
.IP "\fBmax_errata\fR" 4
.IX Item "max_errata"
Maximum number of errata to process at once. Only relevant to format
\&\f(CW\*(C`mail\-archive.com\*(C'\fR
.PP
You can interpolate variables from the \f(CW\*(C`centos errata\*(C'\fR section
elsewhere in the file. See the \fBExample Configuration File\fR for this technique
.PP
The \f(CW\*(C`spacewalk\*(C'\fR section contains the following options:
.IP "\fBserver\fR" 4
.IX Item "server"
Spacewalk server (\s-1FQDN\s0) 
.IP "\fBlogin\fR" 4
.IX Item "login"
Spacewalk username
.IP "\fBpassword\fR" 4
.IX Item "password"
Password to access the server. If you don't specify this option, the
tool will prompt you interactively.
.PP
Each architecture specific section contains the following options:
.IP "\fBpackage_dir\fR" 4
.IX Item "package_dir"
All files for regular updates mentioned in the centos-announce postings
should reside in this directory. reposyncing the \*(L"updates\*(R" repo of
the centos release should do the trick. 
.IP "\fBfasttrack_package_dir\fR" 4
.IX Item "fasttrack_package_dir"
if specified, this directory should contain the package files for the
FastTrack updates. These are distinguished on the centos-announce
postings by the subject line tag \*(L"\s-1FASTTRACK\s0\*(R". This config option will
be ignored unless \fBfasttrack_channel\fR is set.
.IP "\fBchannel\fR" 4
.IX Item "channel"
Channel which contains the update packages. Update errata will be
published to this channel so you should push the updatge packages to
this channel \s-1BEFORE\s0 you run centos\-errata.py.
.Sp
You can have multiple channel names here, just separate them by commas
.IP "\fBfasttrack_channel\fR" 4
.IX Item "fasttrack_channel"
If specified, channel which contains the FastTrack packages. 
\&\*(L"Fasttrack\*(R" errata will be published to this channel if it is
enabled. Otherwise \*(L"fasttrack\*(R" errata will be ignored. 
.Sp
You can have multiple channel names here, just separate them by commas
.Sh "Example Configuration File"
.IX Subsection "Example Configuration File"
An \*(L"all bells and whistles\*(R" config file that pushes errata and
fasttrack errata to i386 and x86_64 CentOS releases. 
.PP
.Vb 10
\&    [centos errata] #Required to identify applicable messages on the
\&    centos-announce mailing list version=5 #Useful for interpolation
\&    below, not used by tool itself release=7 #If true the script will
\&    attempt to use the Redhat Network to populate the errata
\&    description scrape_rhn=False #Set order of places to look for
\&    package NVREA. The only allowable search #strategy is just "dir".
\&    #The "spacewalk" and "satellite" strategies #are deprecated due to
\&    CentOS not using md5sum signatures anymore search_strategies=dir
\&    #Maximum number of errata to process at once. Only relevant to
\&    format 'mail-archive.com' #max_errata
.Ve
.PP
.Vb 5
\&    [spacewalk] server=spacewalk.bioss.sari.ac.uk login=dnutter
\&    #Location of content on spacewalk server. Only used for search
\&    strategy of satellitedir satellite_dir=/var/satellite #The tool
\&    will prompt you if you don't specify a password
\&    #password=reallysecret
.Ve
.PP
.Vb 3
\&    #Per-architecture configurations. Errata will be published for all
\&    #architectures listed in sections below.  See the script for list
\&    #of valid arches.
.Ve
.PP
.Vb 13
\&    #[i386] All files for regular updates mentioned in the
\&    #centos-announce postings should reside in this
\&    #directory. reposyncing the "updates" repo of your fave centos
\&    #release should do the trick.
\&    #package_dir=/usr/ghost/RH_install/CentOS/%(version)s.%(release)s/updates/i386/RPMS/
\&    #All files for FastTrack updates should reside here.
\&    #fasttrack_package_dir=/usr/ghost/RH_install/CentOS/%(version)s.%(release)s/fasttrack/i386/RPMS/
\&    #Update errata will be published to this channel so you should
\&    #push the packages in the directory above to this channel BEFORE
\&    #you run centos-errata.py.
\&    #channel=centos-i386-updates-%(version)s.%(release)s Fasttrack
\&    #errata will be published to this channel
\&    #fasttrack_channel=centos-i386-fasttrack-%(version)s.%(release)s
.Ve
.PP
.Vb 6
\&    [x86_64]
\&    package_dir=/usr/ghost/RH_install/CentOS/%(version)s.%(release)s/updates/x86_64/RPMS/
\&    #package_dir=/tmp/testrpms
\&    channel=centos-x86_64-updates-%(version)s.%(release)s
\&    #fasttrack_package_dir=/usr/ghost/RH_install/CentOS/%(version)s.%(release)s/fasttrack/x86_64/RPMS/
\&    #fasttrack_channel=centos-x86_64-fasttrack-%(version)s.%(release)s
.Ve
.PP
#TODO: change channel naming convention to match the spacewalk-common-channels script (Mohammed Arafa)
.SH "KNOWN ISSUES"
.IX Header "KNOWN ISSUES"
.Sh "Multiple CentOS releases"
.IX Subsection "Multiple CentOS releases"
Currently the only way to support multiple centos releases
(e.g. CentOS 5 and CentOS 6) is to have separate config files for
each. 
.PP
So to push CentOS 5 you might do:
.PP
.Vb 1
\&  centos-errata.py /tmp/centos-digest-message.txt
.Ve
.PP
And CentOS 6:
.PP
.Vb 1
\&  centos-errata.py -c centos-6.cfg /tmp/centos-digest-message.txt
.Ve
.Sh "Input formats"
.IX Subsection "Input formats"
\&\s-1MBOX\s0 format is not supported for input. It should be
.PP
Errata are very basic. If you want full errata, then buying Satellite
is your best bet
.Sh "Error checking"
.IX Subsection "Error checking"
The tool does not check to see if the \f(CW\*(C`update_channel\*(C'\fR exists before
attempting to create and publish an errata. 
.Sh "Automatic package pushing"
.IX Subsection "Automatic package pushing"
Ideally the tool should try and push missing packages to the named
\&\f(CW\*(C`update_channel\*(C'\fR, if they exist on disk.
.PP
Unfortunately the \s-1XMLRPC\s0 api does not seem to support an
\&\f(CW\*(C`pushPackage\*(C'\fR function (unless I'm being blind) so adding this
function would require importing the necessary code from \f(CW\*(C`rhnpush\*(C'\fR
.Sh "Reliant on consistent email from centos-announce"
.IX Subsection "Reliant on consistent email from centos-announce"
Since the format of these emails has been inferred rather than being
documented this script may not be able to parse some errata messages
.PP
Minor formatting changes to the emails on centos-announce can prevent
the script from recognizing messages as errata, or doing the right
thing. Usually, editing the source message is sufficient to correct
the problem and it is rare.
.Sh "Errata Updates"
.IX Subsection "Errata Updates"
Existing errata are not updated, instead you must delete and recreate
them.
.Sh "Errata dates"
.IX Subsection "Errata dates"
Limitations in the spacewalk \s-1API\s0 for creating errata mean that
creation and update dates of errata are the time they were created in
spacewalk, not when the errata were announced by CentOS. As a
convenience, this tool will place the announcement date in the \*(L"notes\*(R"
field of the errata.
.Sh "Search strategies"
.IX Subsection "Search strategies"
Only the \*(L"dir\*(R" search strategy works as the other two (\*(L"satellitedir\*(R"
and \*(L"spacewalk\*(R") rely on knowing the md5sum of the package
beforehand. 
.PP
Unfortunately CentOS have stopped sending the md5sum with each
announce email due to md5 collision issues. Now they send a sha256sum,
which is no good for our purposes!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIrhn\-tool\fR\|(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\& David Nutter (davidn@bioss.ac.uk),
\& Raal Goff (raal goff@zettaserve.com) and
\& Jeremy Davis (jddavis@godaddy.com)
.Ve
.PP
.Vb 1
\& Based on original code by Lars Jonsson (ljonsson@redhat.com).
.Ve