Quickstart doc issues/suggestions - part 1

[dclark]

Here are my notes from initial setup of bcfg2.

http://trac.mcs.anl.gov/projects/bcfg2/wiki/QuickStart

• Disambiguation: It is not clear if the choice is to download the demo repository *and* to "Setup from scratch" or *or* to "Setup from scratch". The most obvious conclusion is *or* since the "from scratch" instructions include making directories that are included in the demo repo, however this is confusing as well, as the two initial setup paths lead to very different initial states.
  • Action: Try to do both, ignoring the duplicative instructions between the two.
• 2a Issue: The instructions need to be updated to be more generic re: platforms. The questions I had were:
  • "I don't have a centos system, so how do I do initial setup?"
  • "Do the Group name and toolset strings matter (i.e. do they mesh with some bcfg2 internals), or are they just arbitrary strings?"
  • "What are the standard (or required) names for my operating system/toolset? I want to see a link to a stadards document that defines things like that."
    • Action: Finally realize that there is already a line "<Group toolset="debian" name="debian"/>" in the demo repo group.xml file. Decide to use that.
• 2b Typo: /Metadata.groups.xml should be /Metadata/groups.xml
  • Action: change name='centos' to name='debian'. IMHO 'centos' needs to be replaced througout the document with something that is obviously a variable.
• 2b Issue: The "This will result in <repo>/Metadata/groups.xml" line shows a file that contains lines that were not put in the file in previous steps. IMHO it would be better to just start off with the finished file, and then write commentary on what the things in it mean. There is also a point of confusion in that this is not what the entire file will look like if the demo repo is installed.
  • Action: Save copy of groups.xml to groups.xml.orig, and make groups.xml look like example, replacing redhat/rh with debian.
• 3 Action: Pretty clear that the demo clients.xml needs to be replaced by this file. For people who like to type instead of cut-and-paste, it might help to note that you need to remove the trailing slash in the demo repository file, as that would be somewhat easy to miss.
• 3 Question: Should "testhostname" be replaced by my actual host name? If so, in hostname or fully-qualified host name form?
  • 3 Action: Replace "testhostname" by my test hosts' actual fully-qualified host name.
• 4 Issue: If the demo repo is installed, <repo>/Base/converted.xml is not a new file.
  • Action: replace contents of <repo>/Base/converted.xml with version from website.
• Intermission 2: "The files named converted.xml were created by the repo format converted that i wrote for the 0.7->0.8 conversion. - "What does this mean? Should I care?" -- I assume that what this is saying is that there is some utility that converts files from a 0.7 format to a 0.8 format and names some of them converted.xml for some reason -- howewver IMHO this information is just distracting/confusing in a Quick Start guide, which will presumably only be used by people starting with the version the Quick Start describes. If there are historical file names, why not just rename things for the guide / in the demo repo?
  • This could use some more explanition: "Base uses it to accumulate a list of all independent config entries that a client should get (ie non-bundle entries)."
• 5 Issue: IMHO instead of a possibly-sensitive file like /etc/motd, why not just use some file that will just show that things are working, like /tmp/motd or /etc/motd.bcfg2 or something like that?
  • Action: Do this instead of what doc says.
• 5 Confusion: Where is this real-motd file coming from? I assume that this is /etc/motd if it exists, however IMHO it would be useful to add something to that file, so that is is obvious the file gets changed when it is copies.
  • Action: Just make a new file <repo>/Cfg/etc/motd.bcfg2/motd.bcfg2 with the text "Yay, bcfg2 is working!"
• 5 Issue: "See the example repo for details." -- There isn't actually an example of :info usage in the demo repo as far as I can see.
• Random issue: It might be useful to make bcfg2-server ignore editor autosave files in common patterns, i.e. #*# and *~ and .*.swx (was getting """Failed to read file /usr/local/var/lib/bcfg2/Base/#converted.xml#save#""" and """Failed to read file /usr/local/var/lib/bcfg2/Base/.converted.xml.swx""")
• Install, Configure, and Run the Client:
  • For example purposes, can't the server also run the client? That's the hostname name I entered in place of "testhostname" before.
  • Action: assume this is the case and run bcfg2 -q -v -d -n on same box as server. Got Error:

    nasa:/var# bcfg2 -q -v -d -n
    {'profile': False, 'dryrun': True, 'verbose': True, 'paranoid': False, 'setup': '/usr/local/etc/bcfg2.conf', 'cache': False, 'help': False, 'remove': False, 'server': 'https://config.notesdev.ibm.com:6', 'quick': True, 'bundle': False, 'file': False, 'debug': True, 'password': '<password>', 'build': False}
    GetProbes completed successfully
    RecvProbeData completed successfully
    GetConfig completed successfully
    Fatal error: Failed to load server-specified toolset: debian
    

  • Action: Search for "rh" lib/bcfg2/lib/python2.4/site-packages/Bcfg2/Client; find nothing; Search for "toolset"; find what looks like a set of toolsets, try replacing 'toolset="debian"' with 'toolset="Debian"' in groups.xml, and try run again. Results: same issue
• Friend comes over, more Evangelian to watch... Open bug with this file so far, wait for feedback on how to fix toolset issue.

[desai]

I think that I have gotten all of these issues resolved in the QuickStart?. I am going to make a separate ticket as a long-term issue for getting all of the file name patterns for temporary editor files.