[etch-devel] SF.net SVN: etch:[115] trunk/client

[<jh...@us...>]

Revision: 115
          http://etch.svn.sourceforge.net/etch/?rev=115&view=rev
Author:   jheiss
Date:     2009-10-12 23:44:00 +0000 (Mon, 12 Oct 2009)

Log Message:
-----------
Create etch manpage, add it to the client packages.

Simplify the etch help output now that more details can be put into the
man page.

Rename etch.rb to etchclient.rb to reflect its purpose.

Add etch.rb and versiontype.rb to the packages

Modified Paths:
--------------
    trunk/client/Makefile
    trunk/client/etch
    trunk/client/etch-client.spec

Added Paths:
-----------
    trunk/client/etch.8

Modified: trunk/client/Makefile
===================================================================
--- trunk/client/Makefile	2009-10-12 23:36:25 UTC (rev 114)
+++ trunk/client/Makefile	2009-10-12 23:44:00 UTC (rev 115)
@@ -1,6 +1,6 @@
 BUILDROOT=/var/tmp/etch-client-buildroot
 # Grab the current version from the library
-VER=$(shell ruby -e "$$:.unshift('.'); require 'etch'; puts Etch::Client::VERSION")
+VER=$(shell ruby -e "$$:.unshift('.'); require 'etchclient'; puts Etch::Client::VERSION")
 
 all:
 
@@ -22,8 +22,14 @@
 	cp -p etch_to_trunk $(BUILDROOT)/usr/sbin
 	chmod 555 $(BUILDROOT)/usr/sbin/etch_to_trunk
 	mkdir -p $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8
-	cp -p etch.rb $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8
+	cp -p etchclient.rb $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8/etchclient.rb
+	cp -p ../server/lib/etch.rb $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8
 	chmod 444 $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8/etch.rb
+	cp -p ../server/lib/versiontype.rb $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/usr/lib/ruby/site_ruby/1.8/versiontype.rb
+	mkdir -p $(BUILDROOT)/usr/share/man/man8
+	cp -p etch.8 $(BUILDROOT)/usr/share/man/man8
 	mkdir -p $(BUILDROOT)/etc/etch
 	cp -p ca.pem $(BUILDROOT)/etc/etch
 	cp -p dhparams $(BUILDROOT)/etc/etch
@@ -53,8 +59,14 @@
 	cp -p etch_to_trunk $(BUILDROOT)/usr/sbin
 	chmod 555 $(BUILDROOT)/usr/sbin/etch_to_trunk
 	mkdir -p $(BUILDROOT)/usr/local/lib/site_ruby/1.8
-	cp -p etch.rb $(BUILDROOT)/usr/local/lib/site_ruby/1.8
+	cp -p etchclient.rb $(BUILDROOT)/usr/local/lib/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/usr/local/lib/site_ruby/1.8/etchclient.rb
+	cp -p ../server/lib/etch.rb $(BUILDROOT)/usr/local/lib/site_ruby/1.8
 	chmod 444 $(BUILDROOT)/usr/local/lib/site_ruby/1.8/etch.rb
+	cp -p ../server/lib/versiontype.rb $(BUILDROOT)/usr/local/lib/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/usr/local/lib/site_ruby/1.8/versiontype.rb
+	mkdir -p $(BUILDROOT)/usr/share/man/man8
+	cp -p etch.8 $(BUILDROOT)/usr/share/man/man8
 	mkdir -p $(BUILDROOT)/etc/etch
 	cp -p ca.pem $(BUILDROOT)/etc/etch
 	cp -p dhparams $(BUILDROOT)/etc/etch
@@ -85,8 +97,14 @@
 	rm $(BUILDROOT)/usr/sbin/etch_to_trunk.tmp
 	chmod 555 $(BUILDROOT)/usr/sbin/etch_to_trunk
 	mkdir -p $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
-	cp -p etch.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
+	cp -p etchclient.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8/etchclient.rb
+	cp -p ../server/lib/etch.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
 	chmod 444 $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8/etch.rb
+	cp -p ../server/lib/versiontype.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8/versiontype.rb
+	mkdir -p $(BUILDROOT)/usr/share/man/man8
+	cp -p etch.8 $(BUILDROOT)/usr/share/man/man8
 	mkdir -p $(BUILDROOT)/etc/etch
 	cp -p ca.pem $(BUILDROOT)/etc/etch
 	cp -p dhparams $(BUILDROOT)/etc/etch
@@ -121,7 +139,7 @@
 # core dumping when running etch.  The Sunfreeware ruby seems to work.
 # Sunfreeware doesn't play well with pkg-get, so we create a bit of a
 # hybrid.  We still express all the dependencies against CSW, and put
-# our library file (etch.rb) into /opt/csw.  We modify etch to use
+# our library file (etchclient.rb) into /opt/csw.  We modify etch to use
 # the Sunfreeware ruby in /usr/local/bin, but then tell it to also look
 # in the /opt/csw directory for libraries.
 # I'm going to guess that the smaller utilities like etch_to_trunk won't have
@@ -147,8 +165,14 @@
 	rm $(BUILDROOT)/usr/sbin/etch_to_trunk.tmp
 	chmod 555 $(BUILDROOT)/usr/sbin/etch_to_trunk
 	mkdir -p $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
-	cp -p etch.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
+	cp -p etchclient.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8/etchclient.rb
+	cp -p ../server/lib/etch.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
 	chmod 444 $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8/etch.rb
+	cp -p ../server/lib/versiontype.rb $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8
+	chmod 444 $(BUILDROOT)/opt/csw/lib/ruby/site_ruby/1.8/versiontype.rb
+	mkdir -p $(BUILDROOT)/usr/share/man/man8
+	cp -p etch.8 $(BUILDROOT)/usr/share/man/man8
 	mkdir -p $(BUILDROOT)/etc/etch
 	cp -p ca.pem $(BUILDROOT)/etc/etch
 	cp -p dhparams $(BUILDROOT)/etc/etch

Modified: trunk/client/etch
===================================================================
--- trunk/client/etch	2009-10-12 23:36:25 UTC (rev 114)
+++ trunk/client/etch	2009-10-12 23:44:00 UTC (rev 115)
@@ -3,11 +3,11 @@
 # Etch configuration file management tool
 ##############################################################################
 
-# Ensure we can find etch.rb
+# Ensure we can find etchclient.rb
 $:.unshift File.dirname(__FILE__)
 
 require 'optparse'
-require 'etch'
+require 'etchclient'
 
 #
 # Parse the command line options
@@ -16,15 +16,15 @@
 options = {}
 @generateall = nil
 
-opts = OptionParser.new
+opts = OptionParser.new(nil, 24, '  ')
 opts.banner = 'Usage: etch [options] [/path/to/config/file]'
-opts.on('--generate-all', 'Can be used instead of giving a specific file to generate.') do |opt|
+opts.on('--generate-all', 'Request all configuration.') do |opt|
   @generateall = opt
 end
-opts.on('--dry-run', '-n', 'Prints contents of generated files instead of writing them out to disk.') do |opt|
+opts.on('--dry-run', '-n', 'Make no changes.') do |opt|
   options[:dryrun] = opt
 end
-opts.on('--damp-run', "Perform a dry run but run 'setup' entries for files.  Normally all setup/pre/post entries are ignored for a dry run.  However, files with setup entries will generally fail to build if the setup entry hasn't been run.") do |opt|
+opts.on('--damp-run', "Perform a dry run but run 'setup' entries for files.") do |opt|
   # Rather than sprinkle checks of two different variables throught the code, if
   # we're asked to do a damp run then just set the dry run flag to a unique
   # value.  Then we can just check for that specific value at the one place where
@@ -32,41 +32,44 @@
   # entries.
   options[:dryrun] = 'damp'
 end
-opts.on('--interactive', 'Causes etch to pause before making each change and prompt the user for confirmation.') do |opt|
+opts.on('--interactive', 'Prompt for confirmation before each change.') do |opt|
   options[:interactive] = opt
 end
-opts.on('--full-file', 'Normally etch will print a diff to show what changes it will make to a file.  This will cause etch to display the full new file contents instead.') do |opt|
+opts.on('--full-file', 'Display full new file contents instead of a diff.') do |opt|
   options[:fullfile] = opt
 end
-opts.on('--filename-only', 'Similar to the previous option, but in the opposite direction.   Etch will only display the name of file to be changed.') do |opt|
+opts.on('--filename-only', 'Display filename of changed files instead of a diff.') do |opt|
   options[:filenameonly] = opt
 end
 opts.on('--disable-force', 'Ignore the disable_etch file.  Use with caution.') do |opt|
   options[:disableforce] = opt
 end
-opts.on('--lock-force', 'Force the removal of any existing lockfiles.  Normally only lockfile over 2 hours old are removed.') do |opt|
+opts.on('--lock-force', 'Force the removal of any existing lockfiles.') do |opt|
   options[:lockforce] = opt
 end
-opts.on('--debug', 'Print lots of messages about what etch is doing') do |opt|
-  options[:debug] = opt
+opts.on('--local DIR', 'Read configuration from local directory, not server.') do |opt|
+  options[:local] = opt
 end
-opts.on('--server SERVER', 'Point etch to an alternate server') do |opt|
+opts.on('--server SERVER', 'Point etch to an alternate server.') do |opt|
   options[:server] = opt
 end
-opts.on('--tag TAG', 'Request a specific repository tag from the server') do |opt|
+opts.on('--tag TAG', 'Request a specific repository tag from the server.') do |opt|
   options[:tag] = opt
 end
-opts.on('--test-base TESTDIR', 'Use an alternate local working directory (for use by test suite only)') do |opt|
+opts.on('--key PRIVATE_KEY', 'Use this private key for signing messages to server.') do |opt|
+  options[:key] = opt
+end
+opts.on('--test-base TESTDIR', 'Use an alternate local working directory.') do |opt|
   options[:varbase] = opt
 end
-opts.on('--key PRIVATE_KEY', 'Use this private key for signing messages that are sent to the server') do |opt|
-  options[:key] = opt
+opts.on('--debug', 'Print lots of messages about what etch is doing.') do |opt|
+  options[:debug] = opt
 end
-opts.on('--version', 'Show etch client version') do |opt|
+opts.on('--version', 'Show etch client version.') do |opt|
   puts Etch::Client::VERSION
   exit
 end
-opts.on_tail("-h", "--help", "Show this message") do
+opts.on_tail('-h', '--help', 'Show this message.') do
   puts opts
   exit
 end

Modified: trunk/client/etch-client.spec
===================================================================
--- trunk/client/etch-client.spec	2009-10-12 23:36:25 UTC (rev 114)
+++ trunk/client/etch-client.spec	2009-10-12 23:44:00 UTC (rev 115)
@@ -14,7 +14,10 @@
 %defattr(-,root,root)
 /usr/sbin/etch
 /usr/sbin/etch_to_trunk
+/usr/lib/ruby/site_ruby/1.8/etchclient.rb
 /usr/lib/ruby/site_ruby/1.8/etch.rb
+/usr/lib/ruby/site_ruby/1.8/versiontype.rb
+/usr/share/man/man8/etch.8
 /etc/etch
 /usr/sbin/etch_cron_wrapper
 /etc/cron.d/etch

Added: trunk/client/etch.8
===================================================================
--- trunk/client/etch.8	                        (rev 0)
+++ trunk/client/etch.8	2009-10-12 23:44:00 UTC (rev 115)
@@ -0,0 +1,203 @@
+.TH etch 8 "October 2009"
+
+.SH NAME
+
+.B etch
+\- Configuration management for Unix systems
+
+.SH SYNOPSIS
+
+.B etch
+.RB [ --generate-all ]
+.RB [ --dry-run | \-n ]
+.RB [ --damp-run ]
+.RB [ --interactive ]
+.RB [ --full-file ]
+.RB [ --filename-only ]
+.RB [ --disable-force ]
+.RB [ --lock-force ]
+.RB [ --debug ]
+.RB [ --local
+.IR DIR ]
+.RB [ --server
+.IR SERVER ]
+.RB [ --tag
+.IR TAG ]
+.RB [ --test-base
+.IR TESTDIR ]
+.RB [ --key
+.IR PRIVATE_KEY ]
+.RB [ --version ]
+.RB [ --help | \-h ]
+.RI [ "file ..." ]
+
+.SH DESCRIPTION
+
+Etch is a tool for managing the configuration of Unix systems. Etch can manage
+text or binary files, links and directories. The contents of files can be
+supplied from static files or generated on the fly by scripts or templates.
+Permissions and ownership as well as any pre or post commands to run when
+updating the file are configured in simple XML files.
+
+.SH OPTIONS
+.TP
+.B --generate-all
+Request that the server generate and send over all available configuration.
+Can be used instead of specifying specific files to request.
+.TP
+.B --dry-run | \-n
+.B etch
+will not make any changes to the system.  Contents of generated config
+files are displayed instead of being written to disk.
+.TP
+.B --damp-run
+Perform an almost dry run, except that 'setup' entries for files are run.
+Normally all setup/pre/post entries are ignored for a dry run.  However, files
+with setup entries will generally fail to build properly if the setup entry
+hasn't been run.  This allows you to preview the full and correct
+configuration while making minimal changes to the system.
+.TP
+.B --interactive
+Causes
+.B etch
+to pause before making each change and prompt the user for
+confirmation.
+.TP
+.B --full-file
+Normally
+.B etch
+will print a diff to show what changes it will make to a file. This will cause
+.B etch
+to display the full new file contents instead.  Useful if the diff is hard to
+read for a particular file.
+.TP
+.B --filename-only
+Normally
+.B etch
+will print a diff to show what changes it will make to a file. This will cause
+etch to display only the name of file to be changed.  Useful on the initial
+run during your system build process or other times when you want less output.
+.TP
+.B --disable-force
+Ignore the disable_etch file.  Use with caution.  Typically used with
+--interactive or --dry-run to evaluate what would happen if etch were
+re-enabled.
+.TP
+.B --lock-force
+.B Etch
+does per-file internal locking as it runs to prevent problems with
+simultaneous instances of the
+.B etch
+client stepping on each other.
+.B Etch
+automatically cleans up lockfiles over two hours old on the assumption that
+any lockfiles that old were left behind by a previous instance that failed for
+some (hopefully transient) reason. In a large environment you don't want to
+have to run around manually cleaning up lockfiles every time a full disk or
+unavailable package server or other transient failure causes
+.B etch
+to fail
+temporarily. This option forces the removal of any existing lockfiles no
+matter how old. Useful if a buggy configuration or local environmental issue
+caused
+.B etch
+to abort and you want to immediately retry.
+.TP
+.BI --local " DIR"
+Read configuration from a local directory rather than requesting it from
+a server.
+.TP
+.BI --server " SERVER"
+Point
+.B etch
+to an alternate server, specified in the form of a URL.
+.TP
+.BI --tag " TAG"
+Request a specific repository tag from the server.  Tags are directory paths
+relative to /etc/etchserver by default.  Thus examples might be
+.I trunk
+for /etc/etchserver/trunk, or
+.I branches/mytestbranch
+for /etc/etchserver/branches/mytestbranch.
+.TP
+.BI --key " PRIVATE_KEY"
+Use an alternate SSH private key file for signing messages that are sent to
+the server.
+.TP
+.BI --test-base " TESTDIR"
+Use an alternate local working directory instead of /var/etch.  Generally only
+used for allowing the etch test suite to be run as a non-root user.
+.TP
+.B --debug
+Print lots of messages about what etch is doing.
+.TP
+.B --version
+Show the etch client version and exit.
+.TP
+.B --help | \-h
+Display the etch usage message and exit.
+
+.SH FILES
+
+.TP
+.B /etc/etch/ca.pem
+SSL certificate(s) needed to verify the
+.B etch
+server's identity. If
+.B etch
+is using a server with an https:// URL and if this file exists then
+.B etch
+will not proceed if the server's SSL certificate can't be verified against the
+certs in this file.
+.TP
+.B /etc/etch/dhparams
+The Diffie-Hellman parameters used as part of the SSL connection process. Etch
+comes with a set and there's no need to generate your own, but a new set can
+be generated via "openssl dhparam" if desired. If not present the Ruby SSL
+library will warn that it is using its internal default set of parameters.
+.TP
+.B /var/etch/disable_etch
+If this file is present
+.B etch
+will do nothing other than send a message to the
+.B etch
+server that it is disabled. Any text in this file will be included in
+that message to the server and displayed locally. If you are disabling
+.B etch
+always put a note in this file indicating who you are, today's date, and why
+you are disabling
+.B etch
+so that fellow administrators won't have to guess later why
+.B etch
+was disabled. Re-enabling
+.B etch
+after it has been disabled for a long
+time can be time-consuming, as the person doing so must review any potential
+changes that have been queued up and ensure that they won't interfere with the
+current usage of the system. As such be thoughtful about whether disabling
+.B etch
+is necessary, and re-enable it as soon as possible.
+.TP
+.B /var/etch/history
+A revision history of each
+.B etch
+managed file, stored using the RCS revision control system.
+.TP
+.B /var/etch/locks
+Directory used by the
+.B etch
+internal locking mechanism.  See the --lock-force option for more details.
+.TP
+.B /var/etch/orig
+A backup of the original contents of each
+.B etch
+managed file as it was before etch first touched it.
+
+.SH DIAGNOSTICS
+
+See the --debug option and the server logs.
+
+.SH AUTHOR
+
+.B Etch
+is designed and maintained by Jason Heiss


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.