1.3 docs/installation.txt updates
Tom Jennings <[email protected]>
| Newsgroups | gmane.network.up2date.current.devel |
|---|---|
| Message-ID | <[email protected]> |
I just got current 1.3.1 up and running, and I too had some
problems with installation.txt ("Invalid client certificate"). The
pieces were more or less all there, but a little convoluted.
Below is an edit to installation.txt that I hope addresses the
problems I had. I intentionally left some paragraphs badly
formatted (line length) so that a diff would be easier to
read. !}fmt will fix them. Yell, and I'll do that.
I intentionally left the overall format otherwise untouched.
Summary of changes:
* Some missing/duplicated info between RPM and tarball installs;
untangled.
* Steps in encryption.txt not needed, so dereferenced.
* stunnel.pem: references to, but not created; made clear is same
as current.pem.
* Client must run rhn_register even after editing client config.
I hope this wasn't all obvious and fixed somewhere that I did
not RTFM. My apologies if so.
tomj
# $Id: installation.txt,v 1.1 2002/07/16 18:46:49 tomj Exp $
# Edits/fixes for 1.3 install doc
CURRENT SERVER INSTALLATION INSTRUCTIONS
Please note that Current (and up2date itself) are moderately advanced
system administration topics. If you aren't comfortable with tar, rpm,
general system adminstration, and similar topics, you probably shouldn't
be using this software. I hate to discourage people, but as a professional
system administrator, I'm morally opposed to helping people destroy their
machines.
Current is in very active development right now. You should be willing (and
able) to help debug and test what may turn out to be very wonky software
(especially in the snapshots). If you need to report a problem, please send
it to the mailing list (even if only I can answer the question, it goes into
the archives for others to benefit from).
Bug reports should include any and all tracebacks, what versions of
up2date/rhn_register/Current you were running, and potentially some
details on what packages/config files you were using. If you can't describe
what broke, I will have a tough time helping you.
Between full releases (1.0 and 1.1), the release notes or README will
include any changes/minor incompatibilities. You should DEFINATELY review
the example current.conf between snapshots for changes (I ship my test
config), and you will almost certainly need to recreate your databases.
[Current now versions its databases, and will not run with an out of date
database]
NOTE: !WARNING! ACHTUNG- This server is beta release level at best,
and should be carefully tested and monitored before being trusted with
production clients (workstations OR servers). [The machine the Current
server runs on should be safe] Closed driver on professional course.
Do not attempt these maneuvers. Eat your vegtables.
Hardware/Software you need:
* A good middling server (I use a 600Mhz PIII w/128MB of ram) with enough
hard drive space for whatever packages you want to serve, plus 50-100MB
for the databases. Speed is generally python and network bound at this
point, so a quad xeon box will buy you zip. (Don't let it go to waste -
send it to me)
* Some clients. Any Red Hat Linux version with up2date v2.7 and
it's proper dependancies (python, python-xmlrpc, rpm naturally, etc)
Installation on the server [by rpm]
* Install the rpm. If you're reading this, you've most likely done that
step. :)
Installation on the server [by tar ball]
* Unpack the tar ball. You can either run it from the directory it untarred
into, or 'make install' after editing the Makefile should work. Watch
out for where you want the config file to go. There are also rpms on the
ftp site.
* Create/edit a current.conf file. I include an example with comments that
should get you going. The most important fields are the directories that
you will use for your channels.
* Note that only the noarch RPM version will install all the nicieties
like /etc/init.d/current in the right places.
Installation, continued.
* cadmin is the Current administration program. One of its
functions/commands is "create_certificate". When setting up your server
for the first time, you'll need to run
[root@server current]$ cadmin create_certificate
This will leave a 'current.pem' file and a 'RHNS-CA-CERT' for use later,
in /etc/current.
There should not be a need to regenerate these files as you upgrade
Current.
* Edit the /etc/current/current.conf file to match your site. The included
sample should be examined carefully between major versions.
* In the place where you untarred/RPMed Current, generally /etc/current, run
[user@server current]$ ./cadmin -v printconfig
This will parse and print out the config that Current thinks you made. Its
a good way to catch config file problems.
* Create all the channels that your configured above. You need to run the
following command once per CHANNEL that you configured.
[root@server current]$ cadmin -v create CHANNEL_LABEL
for each channel label in your 'valid_channels' value. It should print out
a whole bunch of lines saying "Adding NAME_OF_PACKAGE" without any errors.
* If installed from noarch RPM: Run "chkconfig current on" (if you want current to always be started
when your server is booted), and/or "service current start" to go ahead
and start current right now. Check your log files and your ps listings to
make sure BOTH stunnel and current started.
* If you did not install via noarch RPM you will need to start
the server manually (also handy for testing):
* Run stunnel to provide https service. Assuming you have created
a certificate using cadmin as above, you must use the same .pem file
as current's:
/usr/sbin/stunnel -d 8081 -r 8080 \
-p /etc/current/current.pem \
-o /etc/current/stunnel.log
Note that if you are using a port number less than 1024, you MUST run this
command as root. You can then run Current itself as any user with access
to the tree and the database (I run it as a user during testing, and
recommend that).
IMPORTANT: Naturally, whatever port numbers you pick for your http and
https ports MUST go into your client machine's /etc/sysconfig/rhn/* files
- otherwise how will they know where to find the server?
Note: Current itself can run on any port: I just picked 8080 because that
is the traditional "high" web server port. Adjust your stunnel command
line and current.conf file if you want a different port.
The rpms available on the ftp site run as root, and use the 8080 and 8081
port numbers by default. I run them as root so they can put the log,
pid, and subsys lock files in the normal RH locations. If you customize
your configuration to point these files elsewhere, there's no reason
you can't run both stunnel and current as a user.
* Now you can run Current itself.
[user@server current]$ ./current
Note: Current will run as a full daemon, running in the background and
disconnecting itself from the controlling tty. To get it to run in
foreground (for testing or whatever) use the -n/--nodaemon command line
switches.
Note: You can override specific entries in the current.conf file at the
command line. For heavy debugging, I often run it as
[user@server current]$ ./current -l - -n -v -v -v -v
which says to not run as a daemon, log to stdout and to log just about
everything.
Installation on the clients:
* Copy the /etc/current/RHNS-CA-CERT file that you created on the server earlier to ALL
of your clients, replacing the /usr/share/rhn/RHNS-CA-CERT file that
Red Hat shipped. This file tells the clients which servers to trust.
Failure to copy this file is, right now, the most common reason for
things not working.
* Make sure that the /usr/share/rhn/RHNS-CA-CERT file is the one that you
created on your server. Things are absolutely guaranteed NOT to work if
you don't copy that file over. (It tells the client which servers to
trust).
* As root, in /etc/sysconfig/rhn/ edit the rhn_register and up2date config
files. The only entries you are required to change for the Current server
are noSSLServerURL and serverURL. (The entries are the same in both files,
and should be identical between rhn_register and up2date).
From Red Hat, they are setup to point to RHN (naturally)
serverURL=https://www.rhns.redhat.com/XMLRPC
and
noSSLServerURL=http://www.rhns.redhat.com/XMLRPC
Change them, either with an editor or the command line config mode, to
serverURL=https://YOUR.SERVER.NAME:8081/XMLRPC
and
noSSLServerURL=http://YOUR.SERVER.NAME:8080/XMLRPC
(Naturally, you should use the same port numbers that you configured
your server to run as - 8080 and 8081 are just the defaults I ship)
* Other entries (in up2date especially) should be configured to best
match your site, but the two above are all that is _required_.
I highly recommend:
debug=1 # Current is beta quality software right now
retrieveOnly=1 # This has been enough to protect my test clients
# from server bugs.
I suggest:
keepAfterInstall=1 # Makes it easier to see what the server did.
networkRetries=1 # I only get one hit in the server log, instead of 5
# This is probably only needed on clients with poor
# net connections anyway.
useGPG=0 # If you have any non-RH packages in your database.
# If you only use Current to serve RH official rpms,
# LEAVE THIS AS 1.
Some other possibilites:
pkgSkipList=; # and
noReplaceConfig=0 # These two options (along with fileSkipList) limit
# the packages the client will consider for upgrading
IF AND ONLY IF you have retrieveOnly set to 1 you can change safely change
pkgSkipList and noReplaceConfig. (Or you are completely comfortable with
wiping the client and starting over). This will make up2date consider the
most possibilities for upgrading. (remember, we aren't testing up2date
itself, but the servers ability to answer questions for it)
I'm not going to specify EXACTLY what your config file should look like -
if you aren't comfortable monkeying with it, Current server is probably
not for you at this point. Naturally, you should make backups of the
original file, if you ever want to use the RHN servers.
* Run rhn_register on the client to register with the server. You will
likely see "it appears that you are already registered" -- continue
anyways. [Why is this?]
* For clients, thats it.
Installation on the clients (advanced):
- For really easy installation on many clients, you can rebuild the
up2date and rhn_register rpms themselves.
- First, you'll need the 2.7.11 up2date and the 2.7.2 rhn_register
source rpms, and all the build requisites.
- Use the RHNS-CA-CERT file you generated when you installed your server
and the files in the docs/client directory, you can build up2date and
rhn_register rpms specific to your server. (There's even a cron job
there to replace rhnsd).
- I am NOT going to document the details of rpm building here: the files
should be fairly self-evident.
Voila. You may now solve world peace. Or something.
Updates, changes, errors, or whatever in these doc should be reported to
the mailing list, [email protected]
Note: Right now, only one channel per arch/os_release combination is
supported. You can "add" packages easily to the base redhat simply by
including multiple dirs per channel - the example config file shows how
this is done (its how I use it).
Note: The example config file implies that I've used a full CD image/ nfs
install tree as my package set. That IS how I do it - I hope for my
situation to be able to have one tree that is used both to install new
clients and keep old ones up2date. However, thats not a requirement - you
just need some rpm files in one or more directories and a place to create a
database.
As a bare minimum, just the published Red Hat errata in a single dir would
make a very valuable Current server for simple/small sites....
Note: During channel creation, if your tree is like mine, there might be
some warnings about duplicate packages (exactly the same package seen twice,
through symlinks). Since thats not a problem for the database to resolve, it
prints a warning and moves on. Nothing _has_ to be done about these
warnings.
Current, in versions prior to 0.9.5, had a problem with multiple versions
of the same package. Thats been fixed - it should automatically handle
(discard) the older versions. Please upgrade.