Re: 1.3 docs/installation.txt updates

Actually, I'm in the process of re-doing the docuemntation in a
different format - the docs released with 1.3.1 are relatively
out-of-date, as my main focus in the patches I've sent Hunter has been
making Current work and work better, and not really documenting
anything.  I'll go through and incorporate any changes in what you sent
into the new format, but I'm not sure when Hunter will be able to get a
new release out, as he's somewhat busy lately.

        Thanks for the input, though - we always need input on what's
good / bad / ugly.  :)

On Tue, 16 Jul 2002, Tom Jennings wrote:

> 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.
> 
> 
> 
> _______________________________________________
> Current-server mailing list
> [email protected]
> http://lists.dulug.duke.edu/mailman/listinfo/current-server

-- 
Thank you,
John Berninger

Systems Administrator		[email protected]
Department of Mathematics	Box 8205, Harrelson Hall
NC State University		Raleigh, NC 27695
Phone:  (919)515-6315		Fax:	(919)515-3798

GPG Key ID: A8C1D45C
        Fingerprint: B1BB 90CB 5314 3113 CF22  66AE 822D 42A8 A8C1 D45C

"Non illegitimi carborundum."
--