
                 CURRENT SERVER INSTALLATION INSTRUCTIONS
                        AKA THE QUICK START GUIDE

Please note that Current (and up2date itself) are moderately advanced 
system administration topics. If you aren't comfortable with tar, rpm,
general system administration, 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 1.5.x 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 releases the RELEASE-NOTES will include any changes/minor
incompatibilities. You should DEFINITELY 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]
                 

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 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 dependencies (python, python-xmlrpc, rpm naturally, etc)


Installation on the server [by rpm]
===================================

The following is a rough outline for setting up a Current server after
installing the Current RPM.  The DocBook documentation should be more
complete and user friendly, but this should be easy to keep updated
and therefore more current.  The full documentation for Current can
always be found in /usr/share/doc/current-<version>.  All actions
below must be done as root.

*) Edit the /etc/current/current.conf file to your liking.  The Apache
web server must be able to write the the log_file given.  At this
point we support two databases where db_type can be 'postgres', 'mysql' or
'pysqlite'.  MySQL and  PostgreSQL database backendd requires you to 
specify the user, host, database, password configs.  The SQLite backend
does not require any extra configuration.  Current will put the 
SQLite database in current_dir/db/current.sqlite

*) Run: cinstall create_apache_config
This sets up Apache for current.

*) Run: cinstall create_certificate
This creates an SSL certificate for your server and up2date clients.
The cert file that the clients need will be in /etc/current.  This will
erase any pre-existing SSL cert that Apache is using.

*) Run: cinstall initdb
This sets up the database schema.  Restart Apache and current should be
operational.

*) Run: cadmin create_channel -r <release> -a <arch> -l <label> -n <name>
This will create a channel for you.  The release must match the version
of the redhat-release or fedora-release package on your clients.  The
arch is 'i386' for normal Intel machines.  The label is a short unique
string used to identify your channel.  The name is a string.  You
may also add -d <description> to give your channel a description.

*) Run: cadmin add_dir -l <label> -d <dir>
Adds a directory to the channel specified by label.  Any RPMs in that
directory tree will be included in the channel.  You may add as many
directories as needed.

*) Run: cadmin scan_channel -l <label>
This scans the directories and updates the database and the on disk
data that Apache serves out to the up2date clients.  You may want to
put this in a cron job.

There you have it.  You should now have a working Current server.

* Note that both SQLite and PostgreSQL require you to periodically 
"VACUUM" the databases.  You'll need to do that to keep the databases
small, fast, and sane.  A rawhide channel can take up to 40 to 100
MB of hard drive space for the database.

* Note that SELinux may need to be disabled to run Current.  SELinux only
allows apache to read files from certain places.  My home directory where
I do development is not one of them.


Installation on the clients:
============================

* 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).

* Please note that if you ever change the "server secret" string in 
  current.conf, you MUST re-register ALL of your clients - they won't 
  be able to authenticate otherwise.
    
* 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).  You may also
  need to change the location of the RHNS-CA-CERT file if you wish to keep
  the certificate for the Current server in a different place.
  
  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/XMLRPC
  and 
  noSSLServerURL=http://YOUR.SERVER.NAME/XMLRPC

  Right now, the default port numbers for Current are the same as for 
  any http/https server: 80 and 443, respectively.
  
* 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.
  
* 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. (as examples - all 2.7 series
  clients work)
  
- 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, issues@current.tigris.org


Note 1: 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 2: 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.

Note 3: rhn_register has been incorporated directly into up2date as of
Red Hat Linux 8.0.

