INSTALLATION

To setup an NRH-up2date server you need : 

1. a RedHat 7.x (or a more recent one) server
2. a functioning up2date client
3. apache able to run perl cgi
4. db3/db4
5. the following perl modules :

	perl-Frontier-RPC
	perl-XML-Parser
	perl-BerkeleyDB

in addition, on RedHat 7.x you will need to install perl-Digest-MD5,
it is installed by default on more recent RedHat servers.

All modules but perl-BerkeleyDB are present in a standard RedHat 
distribution as rpms, and you can get this one here in rpm or tar.gz form:

	http://www.nrh-up2date.org/download/perl-modules/

6. python bsddb3 module, you can download it here in rpm or tar.gz form:

	http://www.nrh-up2date.org/download/python-modules/

7. on RedHat 8.0 or 9 you will need these rpms :

	librpm404
	rpm404-python
	
RedHat 9 does not come with these, but since it comes with the same rpm 
version as RedHat 8.0, the rpms from 8.0 work just fine on 9.

Since the rpm requirements differ between the 7.x and 8.0+ distributions,
NRH-up2date is always provides different rpms for these platforms. You can
distinguish between the 2 by the rpm prefix, for example :

nrh-up2date-1.2.5-2.7x.noarch.rpm is the rpm for RedHat 7.x
nrh-up2date-1.2.5-2.8x.noarch.rpm is for RedHat 8.0 and 9

IMPORTANT : I use RedHat 7.3 as development and production servers, and i
suggest that you use it as a server. You can probably use any 7.x as a server,
but at least for the initial setup it would be wise to follow the
procedures described in this manual, using RedHat 7.3.

This installation procedure was documented using RedHat 7.3, with the latest
up2date client (up2date-2.8.39-1.7.3.rpm). It was also tested with prior RedHat
versions 7.2 and 7.1 - they share the same up2date client versions.
Originally NRH-up2date was designed for the 2.7 up2date clients, so these
should still work too.

Make sure you are using 2.8 or later up2date client on the NRH-up2date server.
We will start with a basic setup : RH 7.3 server, RH 7.3 client, both of
the same architecture (say, Intel i686), and your objective is to provide the
errata updates for all your RedHat machines located in your corporate LAN.

The procedure assumes that you are logged in as root.

Type "up2date --configure" on the server - you should receive a
configuration list. Note the parameter names - they will be used through
the document. For example reference to "storageDir" means the parameter
0 - /var/spool/up2date by default :

0.  storageDir         /var/spool/up2date
1.  networkSetup       Yes
2.  headerCacheSize    40
3.  httpProxy
4.  debug              No
5.  useGPG             Yes
6.  networkRetries     5
7.  removeSkipList     [kernel*]
8.  retrieveOnly       No
9.  keepAfterInstall   No
10. enableProxy        No
11. gpgKeyRing         /etc/sysconfig/rhn/up2date-keyring.gpg
12. proxyUser
13. proxyPassword
14. headerFetchCount   10
15. versionOverride
16. useNoSSLForPackage No
17. enableProxyAuth    No
18. noSSLServerURL     http://www.rhns.redhat.com/XMLRPC
19. noReplaceConfig    Yes
20. sslCACert          /usr/share/rhn/RHNS-CA-CERT
21. noBootLoader       No
22. systemIdPath       /etc/sysconfig/rhn/systemid
23. serverURL          https://www.rhns.redhat.com/XMLRPC
24. pkgSkipList        [kernel*]
25. adminAddress       ['root@localhost']
26. forceInstall       No
27. fileSkipList       []
28. retrieveSource     No

you should clear the "removeSkipList" and "pkgSkipList" values, and set
"keepAfterInstall" to "Yes", so your up2date client would also download kernel
packages, and would not delete packages after it installs them on the local
machine.

First, you have to download all available updates to the local machine. The
simplest way to do that is, go to your closest RedHat updates mirror and
download the latest rpms into "storageDir", this way you will only have to
wait for the headers to download with up2date, and the packages you missed. You
can of course skip this step, but downloading all the packages from RHN will
probably take much more time.

Now, you have to make up2date believe that you have each and every package
installed, so it would download updates for them (otherwise, it will download
updates only for the packages installed, and nothing more). There is an rpm
file in each RedHat distribution, called (for example, on RedHat 7.3) rpmdb-
redhat-7.3-0.20020419.i386.rpm . This rpm contains the full rpm database of the
current RedHat release.

Install that rpm, and then run :

up2date -ud --dbpath=/usr/lib/rpmdb/i386-redhat-linux/redhat/ --force

This will trick up2date to use the full rpm database, and download each and
every updated package for that RedHat version. From my experience, the only
packages up2date will not download is the specialized kernels, like smp, bigmem
and debug. If you need them, you will have to download them manually from
a RedHat mirror directly into "storageDir" .

UP2DATE QUIRKS : i wasn't able to make RedHat 8.0 use the alternate
package database, so i just went on and downloaded all the updates from
my local mirror. I still needed to run up2date once to get the package
list files in "storageDir" .  On RedHat 9, if i provided the --dbpath
parameter, up2date would tell me that i don't have RedHat's gpg key,
which was wrong. I had to disable the useGPG parameter in up2date to be
able to download packages with up2date using --dbpath. Even after that,
it still did not download packages that i already have installed on the
local machine, so i believe that this method of downloading packages
is useless on RedHat 9. I had to the missing packages from the RedHat
updates ftps (there are several other methods of downloading packages
described in this document).

Now your system contains all updates in "storageDir". 
We do need to process all these packages to a form NRH-up2date requires. 
"cd " into storageDir directory. The directory will contain the file
that starts with it's channel name, and ends with a time stamp. Choose the
most current file present, and run the nrh-ctrl script:

	nrh-ctrl -u <package list, like redhat-linux-i386-7.3.20020806033416>

or let the script find the latest package file itself :

	nrh-ctrl -lu

This script will create all internal data structures needed for NRH-up2date
cgi, like the last update date and the dependency list ...

<INTERNALS>
	If you are really interested, the layout of the storage directory
	needed for the XMLRPC cgi to function is as follows :
	file	nrh-listdate		timestamp of the latest package list
	file	provides-list.<timestamp>.db	dependencies existing packages
	provide
	directory listPackages		contains the package list file
	directory getobsoletes		contains the obsoletes list file
</INTERNALS>

If you do not have all the packages of the channel in storageDir, add the 
--partial switch after the packagelist file to skip warnings about missing
files, like this :

	nrh-ctrl -lu --partial

Link your repository to the location NRH expects to find it 
(/var/spool/nrh-up2date/<channel_base_name>) :

# ln -s /var/spool/up2date /var/spool/nrh-up2date/7.3

the last parameter is the RH version number - 7.3. Change if necessary.


Configuring rpm mime types :

Add "rpm" and "hdr" types to /etc/mime.types as application/octet-stream

my corresponding line in /etc/mime.types looks as follows :

	application/octet-stream        bin dms lha lzh exe class so dll rpm hdr

GOTCHA : the default /etc/mime.types contains it's own definition of the "rpm"
file type, so make sure you comment out the following line

	application/x-rpm              rpm

  If you fail to do these changes to /etc/mime.types, RedHat's 8.0 and higher
up2date client will traceback while retrieving headers or rpms from the
server with the following output :

  File "/usr/lib/python2.2/xmlrpclib.py", line 390, in feed
    self._parser.Parse(data, 0)
xml.parsers.expat.ExpatError: not well-formed (invalid token): line 1, column 0

The normal request process of the client to the server is as follows :

https://www.rhns.redhat.com/XMLRPC
	a request to "serverURL" for authentication and to get the latest date
	of the update list

https://www.rhns.redhat.com/XMLRPC/$RHN/redhat-linux-
i386-7.3/listPackages/20020806033416
	a request to "ServerURL/$RHN/redhat-linux-
	i386-7.3/listPackages/<timestamp>" to get the package list

https://www.rhns.redhat.com/XMLRPC/$RHN/redhat-linux-
i386-7.3/getObsoletes/20020806033416
		a request to "ServerURL/$RHN/redhat-linux-
		i386-7.3/getObsoletes/<timestamp>" to get the obsoletes packages
		list

https://www.rhns.redhat.com/XMLRPC/$RHN/redhat-linux-
i386-7.3/getPackageHeader/openssl-0.9.6b-28.i686.hdr

https://www.rhns.redhat.com/XMLRPC/$RHN/redhat-linux-
i386-7.3/getPackage/openssl-0.9.6b-28.i686.rpm
	requests to get the package headers, and package body.


Apache configuration :

All you need to do is to setup apache to provide the appropriate files
to the up2date client requests. The first request by the client is to
authenticate with the server, and to get the latest update date of
the package list. The client will make a request to the "serverURL"
value (look above in "up2date --configure" output).  The server
logic is contained in the XMLRPC CGI script, which is installed
to /usr/share/nrh-up2date/cgi-bin/XMLRPC. Note, that we will not be
configuring the server to employ https, since this step would complicate
out initial configuration, and NRH works fine without it.

This is the most important, and if you are not familiar with apache
configuration, problematic part. The client, by default, accesses the
server at http://<servername>/XMLRPC.  Our XMLRPC script is a cgi,
and to run the cgi, at the root of the server, you must define the root
of your website as a ScriptAlias, meaning that every executable file
in your webroot will be executable by the webserver remotely. Unless
your server will serve only NRH-up2date content, or you are running in
a security-insensitive environment, this is not a secure config, so you
should create a virtual host, that will only serve NRH content on the
server, and define the root of the virtual site as a scriptalias.


There are 3 ways to setup your web server :

1. How to configure for a simple, not secure config :

copy the following to the aliases definitions part of your httpd.conf :

----------------------------------------------

Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getPackageHeader/ "/var/spool/nrh-up2date/7.3/"
Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getPackage/ "/var/spool/nrh-up2date/7.3/"
Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/listPackages/ "/var/spool/nrh-up2date/7.3/listPackages/"
Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getObsoletes/ "/var/spool/nrh-up2date/7.3/getObsoletes/"

ScriptAlias / /usr/share/nrh-up2date/cgi-bin/

----------------------------------------------

7.3 is RH version number. Change if necessary.

2. How to configure for a virtual host serving only NRH-up2date content :

Below is a sample from the virtual hosting configuration of my NRH-up2date
server

----------------------------------------------

#
# Use name-based virtual hosting.
#
NameVirtualHost *

<VirtualHost *>
        ServerName www.nrh-up2date.org
        DocumentRoot /var/www/html/
</VirtualHost>

<VirtualHost *>
        ServerName up2date
        ServerAlias up2date.nrh-up2date.org
        DocumentRoot /usr/share/nrh-up2date/cgi-bin/

        Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getPackageHeader/ "/var/spool/nrh-up2date/7.3/"
        Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getPackage/ "/var/spool/nrh-up2date/7.3/"
        Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/listPackages/ "/var/spool/nrh-up2date/7.3/listPackages/"
        Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getObsoletes/ "/var/spool/nrh-up2date/7.3/getObsoletes/"

        ScriptAlias / /usr/share/nrh-up2date/cgi-bin/
</VirtualHost>

----------------------------------------------

As you can see, the main site is configured to serve the regular /var/www/html/,
and if a client addresses the server by the name "up2date" or "up2date.nrh-
up2date.org", which is configured in my dns to go to the same ip as the main
ip of the server, the content in /usr/share/nrh-up2date/cgi-bin/ will be accessed.

In this config, it is very important that the ScriptAlias line is the last line
in the site configuration section.

3. Configuring the web server the "old" way, like NRH version before 1.3 were
instructing :

The first request by the client is to authenticate with the server,
and to get the latest update date of the package list. The client
will make a request to the "serverURL" value (look above in "up2date
--configure" output).  Generally, this would be the XMLRPC script,
at the root of the web server, but this can be changed, to access
http://<servername>/cgi-bin/XMLRPC. This would ease your apache
configuration, since the only thing you would need to do on the server
was to create the necessary aliases for channels, and put the XMLRPC
script in your cgi-bin directory. This is not a recommended setup, since
up2date was not actually designed to work like this, and this causes
some problems that can be avoided by not using this setup, for example,
the client could in some cases (like after performing a new registration
with a server) reset the serverURL from http://<servername>/cgi-bin/XMLRPC
back to http://<servername>/XMLRPC.

How to configure the server in this case ?
Copy the XMLRPC cgi to your cgi-bin directory : if you downloaded the tar.gz
and ran "install", the file is installed in /usr/share/nrh-up2date/cgi-bin
directory.

# cp /usr/share/nrh-up2date/cgi-bin/XMLRPC /var/www/cgi-bin/

After that, copy the following to the aliases definitions part of your
httpd.conf :

----------------------------------------------

Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getPackageHeader/ "/var/spool/nrh-up2date/7.3/"
Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getPackage/ "/var/spool/nrh-up2date/7.3/"
Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/listPackages/ "/var/spool/nrh-up2date/7.3/listPackages/"
Alias /XMLRPC/$RHN/redhat-linux-i386-7.3/getObsoletes/ "/var/spool/nrh-up2date/7.3/getObsoletes/"

----------------------------------------------


This concludes the 3 different ways to configure your apache. Remember to
restart your apache after making these changes. And don't be tempted to use
the Options ExecCGI at the root of the webserver for solutions 1 and 2 - 
this would not produce the desired result, you must use ScriptAlias, after
all you channels definition.


Client configuration :

To configure a client to connect to a local server to fetch the updates we have
downloaded before, assuming the server's name is "nrh", we will set the
following :

serverURL = http://nrh/XMLRPC

in the 2.8 and higher clients you cannot set serverURL to a value you want
through
# up2date --configure

this will only provide a list of RedHat's servers to choose from, so just
change it in the up2date configuration file at

# vi /etc/sysconfig/rhn/up2date

If the client was already configured to connect to the RHN servers, it means
that it already has a systemid file configured, this file contains a unique
identifier for each computer connecting to the RHN. If this is a freshly
installed system, copy a systemid file from another installation to
/etc/sysconfig/rhn/. If the system is not RH 7.3 - edit the systemid file to
match.

In this document there is a procedure describing how to register your client
(to receive a valid system id from your NRH server) - this step is skipped
here to ease the configuration.

NOTE : If you have used the 3rd method to configure apache, then the procedure
of configuring the clients is more complicated - you must set the following 
values in the client as you see below :

serverURL = http://nrh/cgi-bin/XMLRPC
noSSLServerURL = http://nrh/XMLRPC
useNoSSLForPackage = Yes


You can add additional rpms manually to storageDir, to make them available on
your nrh-up2date server. You can copy the entire contents of the RedHat cd,
and get all the updates from your local mirror, like i do from my local mirror :

wget --passive-ftp -r -nd \
ftp://ftp.free.fr/pub/Distributions_Linux/RedHat/redhat/linux/updates/7.3/en/os/i386/ \
ftp://ftp.free.fr/pub/Distributions_Linux/RedHat/redhat/linux/updates/7.3/en/os/i586 \
ftp://ftp.free.fr/pub/Distributions_Linux/RedHat/redhat/linux/updates/7.3/en/os/i686 \
ftp://ftp.free.fr/pub/Distributions_Linux/RedHat/redhat/linux/updates/7.3/en/os/athlon \
ftp://ftp.free.fr/pub/Distributions_Linux/RedHat/redhat/linux/updates/7.3/en/os/noarch

NOTE : additional rpms means rpms that are in the up2date package list.
NRH-up2date does not currently support adding random packages to a
channel produced in a way described here.

This concludes your basic configuration of the nrh-up2date server. All the
packages that are downloaded by the server will be available to the clients.
You should be able to run "up2date -l" on the client, and receive the
updates package list, and "up2date -u" to update packages.

-----------------------------------------------------------------------

Troubleshooting

At this stage, there are some problems that can arise. You could receive
an "500 internal error" while running up2date on the client. This
means that the XMLRPC cgi is encountering a fatal error - usually
because of some perl modules not installed. You will be able to see
that module are you missing by looking at the apache error log (usually
/var/log/httpd/error_log).

Since i am the developer, i would obviously encounter less errors then
a new user of NRH-up2date. Please help me to extend this section by
reporting your problems (if you have them) to the mailing list. Please
read the BUGS document for the exact procedure for effectively reporting
bugs.

-----------------------------------------------------------------------

Dependency resolution

One of the calls that the server can receive from the client is to resolve
dependencies the client can't resolve by it's own. The server does this
by keeping a list of all dependencies of all the packages in the channel.

If you are not having all the packages present in the storageDir when
updating your repository, the dependencies list will only contain the
dependencies provided by the packages present. If a package requests
dependency from the server that is not provided by the packages present,
the client will report an error - "unresolvable dependencies chain". If
you want dependency resolution to work correctly, you want to have a
full package repository ...

-------------------------------------------------------------------------------

Serving updates for multiple RH versions

You may want to use a single nrh-up2date server to update different
versions of clients (RH 7.1, 7.2, 7.3, 8.0, 9). Do do that you need
first to create the package repositories and copy the basic rpms and
the updates to that directory, as described in the previous paragraph.

First, let's create the repositories : create

mkdir /var/spool/nrh-up2date/7.2 
mkdir /var/spool/nrh-up2date/7.1

or elsewhere, but then create symlinks to these locations.

copy the installation files and the updates into these directories.

There are several ways to download packages for your distributions:
1. Running "up2date -ud" on the machines with the necessary version of RH
installed and copying the updates to the NRH server to the appropriate
directory.  While setting up these channels on the server, you will
need the package list files (redhat-linux-i386-$VERSION.$DATE). Either
copy them from /var/spool/up2date directory from the clients you used
to download the packages from rhn, or get them from

http://www.nrh-up2date.org/pkglists/

  That location will always contain the package lists for the latest
versions of channels present on the NRH demo server. Usually they will
be posted there withing 24 hours from the moment RH updates the channel,
since i am monitoring the RHN updates.

2. You can always download the updates from your nearest
updates.redhat.com mirror - this way all you need to get from the up2date
storageDir from machines with the necessary version of RH is the package
list files.

3. Use nrh-mirror-updates script with an upstream NRH server (it could
also be RHN server, but here you are on your own, legally). This script
would download everything you need, starting from packages to the package
lists and all necessary applet content.

4. You could use the get-redhat-updates.pl script by Iain Buchanan,
which is located at http://www.nrh-up2date.org/download/contrib/
(updates.tar.gz)

-------------------------------------------------------------------------------

Securing the client-server communication

If you remember, the original server urls that were configured into the
up2date client were https - which means that all traffic traveling between
the server and the client is secure. You should be aware that up2date traffic
contains some info about your client systems, so if you are using NRH on your
local lan, you could leave it as is, using http, but over internet you would
probably want to secure this type of information.

The "useNoSSLForPackage" is also set to NO by default, but we turn it on,
since we don't want the package to go through encryption - the only thing
the attacker can do if he intercepts the package is to know what version
or package is installed on a particular machine, which shouldn't do him
any good, since this is supposed be an errata package with no known
vulnerabilities. Also, all packages that are delivered to the client are
checked if they are correctly signed by RedHat gpg key :

5.  useGPG             Yes
11. gpgKeyRing         /etc/sysconfig/rhn/up2date-keyring.gpg

so unless you disable these, you have nothing to worry.

If you are still worried, and want all or some communication to use https,
You can change these values below to suite your taste

16. useNoSSLForPackage No
18. noSSLServerURL     http://www.rhns.redhat.com/XMLRPC
23. serverURL          https://www.rhns.redhat.com/XMLRPC

but beware, there is a caveat. The up2date client checks if the server
https key matches the one stored in

20. sslCACert          /usr/share/rhn/RHNS-CA-CERT

so if you want to use httpd, you will have to copy your server public key
to the client and point "sslCACert" to that certificate.

Generally, the process is simple - the command sequence below is "lifted"
from "Current" project admin script :

openssl genrsa -out server.key 1024
openssl req -new -x509 -days 365 -key server.key -out server.crt
openssl x509 -noout -text -in server.crt > NRHS-CA-CERT
cat server.crt >> NRHS-CA-CERT
mv server.crt /etc/httpd/conf/ssl.crt/
mv server.key /etc/httpd/conf/ssl.key/

now, be careful when generating the key, and check that all RH version
you are planning to support are able to connect to the server. In my tests,
7.1 clients were not able to connect to server who's keys were generated
on RH 7.3. Only when i generated the keys on RH 7.1, all clients were
able to connect. openssl project should really work out these compatability
issues.

Now, you will have to copy the file to /usr/share/rhn/NRHS-CA-CERT of
each client you want to connect through httpd to the server, and set :

19. sslCACert          /usr/share/rhn/NRHS-CA-CERT

Do not just overwrite the client's /usr/share/rhn/RHNS-CA-CERT, because the
next update of up2date will overwrite this file back.

-------------------------------------------------------------------------------

NRH-up2date security features

Starting from version 1.1, NRH includes several security features to help you
limit access to your NRH server only to the users you want. If you are going
to use these features, it is advisable that you use SSL to encrypt your
client-server communications, as described in the previous paragraph.

-------------------------------------------------------------------------------

Using rhn_register to receive a valid system id from your server

To receive a valid system id from your NRH-up2date server,

"vi /etc/sysconfig/rhn/rhn-register" for 7.x clients, or 
"vi /etc/sysconfig/rhn/up2date" for 8.0 clients, since 8.0 has 
deprecated the rhn_register package.

change serverURL to your NRH server, like me :

"serverURL=http://nrh.nrh-up2date.org/XMLRPC"

and run rhn_register to generate your new systemid file for your machine
in your NRH network. The server can be setup to accept any username
and password during registration - this is the default if you want to
just generate systemid for a new machine. You can also limit people from
registering with your NRH server, by creating the "/etc/nrh/anon_passwd"
file, and putting there the password you would like people to use while
registering. In this case the username used during the registration
must be "anonymous", and the password identical to the contents of
"/etc/nrh-up2date/anon_passwd". Once you have created the file, no one will
be able to register with your server with a random username and password.

During registration process, no information is collected. The only fields
that must be completed is where your username and password, if chosen -
all the other screens can be skipped by pressing "F12"

To secure the system id, a checksum is used. If you want people not
to be able to modify the systemid they have, please put some one-line
random string into "/etc/nrh-up2date/secret" - this string will be used
to encode the checksum of the systemid, so if someone tries to change the
file he has, he will not be able to regenerate the checksum. Be aware,
that if you change the secret on the server, all previously issued
systemids will become invalid.

You can also use RedHat's rhnreg_ks to register the system from command
line. Run "rhnreg_ks --help" to find out the options available.

Please remember, that the server doesn't store any information about
clients that use it - authentication is based on the systemid file
parameters provided by the client every time it accesses the server

-------------------------------------------------------------------------------

Basic security for server access

By default, NRH server will accept any systemid, whether it is from RHN or
NRH, or even modified version of any of these - checksum check on the
systemid is not enforced (though it still must be well formatted systemid
file - basic functionality requires this), so anyone can point his up2date
client to your server, and update his system from it. If the
"/etc/nrh-up2date/security" file exists, NRH will accept only clients with
valid systemids issued by your server. Any other clients will get an error
and be rejected.

-------------------------------------------------------------------------------

Implement access control for the rpm repository

Generally, even if you configure your server to reject any non-native
systemid, one could still download packages from your server by using the
urls up2date uses to download packages, waisting your bandwidth. up2date
includes an access authentication token what it receives at login time, and
should change with each new login. This token is sent to the server each
time the client makes a request. I have written a 70-line script that is a
mod_perl access authorization module (if you are interested to read about the
technology, read http://perl.apache.org/docs/1.0/guide/security.html), which
will basically allow to download rpms only by people who successfully
authenticated against your server with any systemid, or you could enforce
that only the users that have systemid issued by your server can download
rpms. Ip based restrictions also implemented, since the perl based module is
not easy to configure along the standard access modules in apache to protect
the same location. If you want to set it up, all the documentation you need
is in remarks in the start of the module (Access.pm). It will report allowed
or denied attempts to download content as warnings in the apache error log.

-------------------------------------------------------------------------------

Setting ServerURL

Until up2date 2.8, one could run "up2date --configure" and set the serverURL
to any url you would like. I guess RedHat wants to prevent you from using
NRH and similar projects, so starting from version 2.8 you cannot set serverURL
to anything, except RedHat's servers. A list of servers is requested from the
current serverURL, and you can only choose from what it returns. To change the
serverURL to your server, you must manually edit the configuration files at
"/etc/sysconfig/rhn/up2date" and "/etc/sysconfig/rhn/rhn_register" .

------------------------------------------------------------------------------

Monitoring updates available on other servers

Since the release of NRH-up2date 1.1.1, nrh-mirror-updates is included
for this exact purpose. It is installed to /usr/sbin, documentation is
included as comments in the beginning of the file.

------------------------------------------------------------------------------

Creating your own channel

From time to time you may want to create your own channel. This can be
done to provide your own, updated package list for the general channels
(the os_release channels) - be aware, that this is not the recommended
way to maintain an NRH server, since this way you are not in sync with
RedHat's channels; or to create an additional channel, to be pushed to
the clients along the general channels, which would contain additional, or
updated packages you would like to distribute along the general channels.

While using this method, you better know what you are doing, and make sure
that your repository directory contains the correct rpms (no duplicated
rpms of different versions, incorrect dependencies, etc).

Starting from version 1.3 of NRH, you can create an "-extra" channel for
each general channel, to contain additional, or updated packages. You
have to create the channel directory, (for example, for 7.3 it should
be /var/spool/nrh-up2date/7.3-extra), and to create the necessary
aliases in httpd.conf. The channel would be seen by the clients as
"redhat-linux-<os_release>-extra"

to create such channel, "cd" into your repository directory, and run

nrh-ctrl -g --channel=redhat-linux-7.3-extra

to create the 7.3-extra channel.

The up2date client is able to handle if the same package appears in
several channels, it simply chooses the most recent package from both
of the channels.  Your only problem is that up2date will check gpg
signatures on your rpms, and refuse to use them. You can disable gpg
checking, but this is not recommended for production. Instead, sign your
packages with your gpg key, and add it to the gpg keyring, configurable
in up2date (usually /etc/sysconfig/rhn/up2date-keyring.gpg).

------------------------------------------------------------------------------

The installation of the APPLET service

The RHN applet functionality is simply put, to provide the client with
an XML based list of errata updates. The APPLET cgi is to be put in the
cgi directory.  The cgi uses the same layout of directories as the XMLRPC
cgi (/var/spool/nrh-up2date/<version>/) for it's data.

When the client accesses the cgi, it provides it's release version
(for example "8.0").  Based on the version , the APPLET will access the
applet-errata.<timestamp>.zlib at the (/var/spool/nrh-up2date/<version>/)
directory, where the timestamp is the last update date of the channel, and
send it to the client. Currently, the applet data updated at the same time
as the channel data, so nrh-listdate contains the timestamp necessary.

There are 2 ways to generate the applet-errata.<timestamp>.zlib file :

As the rest of the NRH system, the APPLET can use "leftovers" from
the standard up2date tools.  After the RedHat's applet connects
to RHN servers, it stores the errata list in a binary form at
~/.rhn-applet.cache file.  The script is able to load the list, and
dump it as ./applet-errata.<timestamp> file in the local directory,
and as ./applet-errata.<timestamp>.zlib , as a compressed version of
the list.  the script is currently intended to be ran at the correct
/var/spool/nrh-up2date/<version>/ directory.

The other way is to use nrh-mirror-updates to get the list from upstream
server.

After the list is generated, you should configure the clients to point
to YOUR server, by altering the file /etc/sysconfig/rhn/rhn-applet. Change
the serverURL to http://your.server/APPLET. After that, your
client should be completely operational. Delete any ~/.rhn-applet.cache
files, to get rid of the cache files, and run rhn-needed-packages at
the command line on RedHat 7.3, or /usr/bin/rhn-applet-tui on redhat
8.0+ : if you didn't get an error - it works ;)


------------------------------------------------------------------------------

Protecting your server from being hammered unintentionally

RedHat's up2date client in versions 8.0 and up has a bug, that in some cases
of misconfiguration will keep hammering the server with the requests to

/cgi-bin/XMLRPC/<content> instead of /XMLRPC/<content>

if you are using the cgi-bin way to place the XMLRPC script, such
hammering can produce a considerable load on the server - one way to
mitigate this "attack" is to insert the following expression in your
httpd.conf :

<LocationMatch "/cgi-bin/XMLRPC/.*">
        Deny from all
</LocationMatch>

Of course, this is not a final solution, because your server will still
respond to these requests by error 403 - access forbidden. Your error
logs will still grow, logging these requests, which could lead to denial
of service.  You could disable logging of such requests by setting the
following in httpd.conf :

SetEnvIf Request_URI "/cgi-bin/XMLRPC/.*" dontlog CustomLog
/var/log/httpd/NRH-log combined env=!dontlog

but this can be problematic, if you want to track these clients and
errors.

You will probably still need to locate the source of the hammering, and
to stop it, or to block the client from accessing the server by setting a
rule at your firewall, usually iptables on the server machine. However,
the procedures described here will protect your machine from high cpu
consumption, since running the XMLRPC cgi takes considerable cpu cycles
- each invocation involves starting a new instance of perl. This cpu
consumption problem will be resolved when NRH will be converted to
mod_perl.

-------------------------------------------------------------------------------

RHAS, ES, WS and other RedHat Enterprise products

My position on RedHat enterprise products is, in short, as follows :

I am not investing time into this, since a person who uses
advanced/enterprise linux is obligated to purchase RedHat network for
each machine he is using. There is no way around it in the license, a
person who doesn't do it, is out of compliance, and the chance
what a person purchases RedHat network, but wants to use local server
does not justify development. To add on top of that, i don't have
access to enterprise RedHat channels or software, so development is not
likely to progress in this direction any time soon.

Now, the long version :

Using NRH-up2date to serve updates to normal RedHat linux releases 
from RHAS server : 

The configuration is actually pretty simple, with a few catches.

1. You cannot use up2date -ud to download packages for your repositories,
you must use other means. 
2. There is no perl-Frontier-RPC, use the one from 7.3. It is installed
into /usr/lib/perl5/vendor_perl/, and on RHAS this path is not in @INC. 
you must move the modules into /usr/lib/perl5/5.6.1/i386-linux/.
3. You need the perl and python Berkley-DB modules, use the ones provided
for RH 7.3 on the NRH-up2date site.
4. If you want to use nrh-mirror-updates, you have to install python2
from 7.3, and rhnlib and pyOpenSSL from 8.0

Using NRH-up2date to serve updates to RedHat Enterprise products :

RHAS channels are different from the standard RedHat linux channels.
While for RedHat 7.3 os_release parameter in systemid is "7.3", and the
channel called redhat-linux-i386-7.3, and for RedHat 8.0 os_release
parameter in systemid is "8.0", and the channel called
redhat-linux-i386-8.0 , and since i have been using only these systems,
i have simple set NRH to derive the channel name returned to the client
on the simple scheme :
 
channel_name = "redhat-linux-i386-".os_release
 
On the other hand, in RHAS there is absolutely no relation between the
os_release parameter (which is 2.1AS), and the channel name (which is
redhat-advanced-server). Since NRH was not designed to handle such case,
it will take me some time to design an appropriate solution for the
problem.
 
The fast solution would be to generate your own package lists, if you
have the packages, so that the channel name would be consistent with the
naming convention that NRH assumes. In /var/spool/nrh-up2date/2.1AS
after you downloaded your packages and package lists, and ran
nrh-clean-repository, to make sure there are no duplicate versions of
the same package, then just run "nrh-generate-pkglist
redhat-linux-i386-2.1AS" . This would also generate the obsoletes list,
that would in turn take care of the problem where nrh-repository-update
expects it. Then, you only need to add aliases (as always) to httpd.conf:
 
Alias /XMLRPC/$RHN/redhat-linux-i386-2.1AS/getPackageHeader/  "/var/spool/nrh-up2date/2.1AS/"
Alias /XMLRPC/$RHN/redhat-linux-i386-2.1AS/getPackage/ "/var/spool/nrh-up2date/2.1AS/"
Alias /XMLRPC/$RHN/redhat-linux-i386-2.1AS/listPackages/ "/var/spool/nrh-up2date/2.1AS/listPackages/"
Alias /XMLRPC/$RHN/redhat-linux-i386-2.1AS/getObsoletes/ "/var/spool/nrh-up2date/2.1AS/getObsoletes/"
 
and it Just Works (TM) .
 
A second solution would be a script that would take RedHat's package
list, that comes in form of redhat-advanced-server-i386.date file, load
it with the xmlrpclib module, replace the channel name
(redhat-advanced-server-i386) for each package in the file with
"redhat-linux-i386-2.1AS", and save the file as
redhat-linux-i386-2.1AS.date. It would also be nice if it generated an
empty obsoletes list, for compatibility. Now, I can create such script,
if someone sends me the package list that he has on his RHAS after
running up2date (If anyone is feeling creative, and has an hour to write
the script, it will be most appreciated ;)

A final solution of course would be to create a list that could map a
channel to os_release - don't expect it soon though, as this would
require major changes.
