syncwrap 2.1.3 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e03ea268f99e5d4fbb0f77975dfb7ddf89652ac1
-  data.tar.gz: 690f532e095db3ef3f15be5e22c15e9c93848e9f
+  metadata.gz: 9a94bbce85319bea7ab7ee215feee79a2f33d2b0
+  data.tar.gz: 8f031221c85ae70474788dfee38e6d5c05e73c3d
 SHA512:
-  metadata.gz: 69cff80b28bba560719fd9564e285f586561fda5e531e83f3398c401a7c1d9a61006e66c1f3b97821ccc9c8f54691a57d1e63597bb44429bb28a7915614bb351
-  data.tar.gz: 8619b3b04a73e551c52feba0e97a451b40521ddf4436a84a0213f7569eb855350979766720cd42b0d8879a0bf26942fe47efb0bfcd991b9b5c9fbd9612c4e335
+  metadata.gz: e480edaffd434f726454f2721e95816d085dde7b9114378d49877fe15f0bc7a09bb88b7e61c1fd9c7ce331692fa003e3f237b6e948f94e5d46f93297fc144b29
+  data.tar.gz: 3f4c2eacd8c0e726e91ef71c403c34b5225aaa8c3526d2a6ace7f5c24b8a46af6feabb36ea3d4b903bc59e3405bbfdf239a385d8ac4d0b0b9b9c4f013c5d0c2d

data/History.rdoc

@@ -1,3 +1,32 @@
+=== 2.2.0 (2014-7-13)
+* New SyncWrap::Component#sh :pipefail option to pass bash flag "-o
+  pipefail" to return the first non-zero command return from a
+  pipeline.  This option defaults to true when the :error (bash -e)
+  option is also true (the default). You should review pipeline usage
+  in your own components as part of upgrading. Internally, the
+  SyncWrap::Hashdot component required an adjustment for this change.
+* Major SyncWrap::PostgreSQL component updates. You need to
+  review and adjust any configuration overrides and constructor
+  properties:
+  * Use templates to consolidate RHEL and Ubuntu configuration. Files
+    moved to sync/postgresql. (#2)
+  * Use distro default PG data directory, by default. Tested
+    Amazon Linux EBS MDRaid mount direct to /var/lib/pgsql9. (#3)
+  * No elevated permissions (trust, etc.) by default (#4)
+  * Configuration is 9.3 ready (9.1-9.3 compatible)
+  * Configuration no longer assumes AWS EBS optimizations, relaxed
+    guarantees. See test/aws/sync.rb sample for new PostgreSQL
+    properties to maintain compatibility.
+* Removed vestigial SyncWrap::Distro package_map and localize package
+  variations to the individual components.
+* SyncWrap::RunUser now creates a _system_ user/group with default
+  home the same as run_dir.
+* Add :ebs_mounts AWS profile option to support HVM-style dev mounts,
+  made apparent by EC2 t2 instance types.
+* Upgrade SyncWrap::JRubyVM default version to 1.7.13
+* Upgrade SyncWrap::CRubyVM default version to 2.1.2
+* Upgrade to aws-sdk ~> 1.46 (no longer depends on uuidtools)
+
 === 2.1.3 (2014-7-8)
 * Use sudo instead of --rsync-path=sudo... for :user on localhost
 * Cleanup the environment for gem_install on different ruby, when

data/Manifest.txt

@@ -54,17 +54,14 @@ sync/etc/corosync/uidgid.d/qpid
 sync/etc/init.d/iyyov.erb
 sync/etc/init.d/qpidd
 sync/etc/sysconfig/pgsql/postgresql.erb
-sync/etc/sysctl.d/61-postgresql-shm.conf
+sync/etc/sysctl.d/61-postgresql-shm.conf.erb
 sync/jruby/bin/jgem
-sync/postgresql/rhel/pg_hba.conf
-sync/postgresql/rhel/pg_ident.conf
-sync/postgresql/rhel/postgresql.conf
-sync/postgresql/ubuntu/environment
-sync/postgresql/ubuntu/pg_ctl.conf
-sync/postgresql/ubuntu/pg_hba.conf
-sync/postgresql/ubuntu/pg_ident.conf
-sync/postgresql/ubuntu/postgresql.conf
-sync/postgresql/ubuntu/start.conf
+sync/postgresql/environment
+sync/postgresql/pg_ctl.conf
+sync/postgresql/pg_hba.conf.erb
+sync/postgresql/pg_ident.conf
+sync/postgresql/postgresql.conf.erb
+sync/postgresql/start.conf
 sync/src/hashdot/Makefile.erb
 sync/src/hashdot/profiles/default.hdp.erb
 sync/src/hashdot/profiles/jruby-common.hdp

data/examples/jruby.rb

@@ -5,7 +5,7 @@ role( :all,
 
 role( :jruby,
       OpenJDK.new,
-      JRubyVM.new( jruby_version: '1.7.10' ),
+      JRubyVM.new( jruby_version: '1.7.13' ),
       Hashdot.new )
 
 host( 'centos-1', RHEL.new, :jruby, internal_ip: '192.168.122.4' )

data/lib/syncwrap/amazon_ws.rb

@@ -86,11 +86,15 @@ module SyncWrap
     # :security_groups:: As per aws-sdk, but the special :default value
     #                    is replaced with a single security group with
     #                    same name as the :region.
-    # :ebs_volumes:: The number of EBS volumes to create an attach to this instance.
+    # :ebs_volumes:: The number of EBS volumes to create and attach to this instance.
     # :ebs_volume_options:: A nested Hash of options, as per
     #                       {AWS::EC2::VolumeCollection.create}[http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/EC2/VolumeCollection.html#create-instance_method]
     #                       with custom default :size 16 GB, and the same
     #                       :availibility_zone as the instance.
+    # :ebs_mounts:: Device mounting scheme. The value :sdf_p indicates
+    #               "/dev/sd[f-p]", and should be used for HVM instances.
+    #               The default scheme is currently :sdh1_6 "/dev/sdh[1-6]".
+    #               See {EC2: Block Device Mapping}[http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html]
     # :lvm_volumes:: Ignored here.
     # :roles:: Array of role Strings or Symbols (applied as Roles tag)
     def aws_create_instance( name, opts = {} )
@@ -103,6 +107,7 @@ module SyncWrap
       iopts = opts.dup
       iopts.delete( :ebs_volumes )
       iopts.delete( :ebs_volume_options )
+      iopts.delete( :ebs_mounts )
       iopts.delete( :roles ) #-> tags
       iopts.delete( :description ) #-> tags
       iopts.delete( :tag ) #-> tags
@@ -150,7 +155,12 @@ module SyncWrap
         attachments = opts[ :ebs_volumes ].times.map do |i|
           vol = ec2.volumes.create( vopts )
           wait_until( vol.id, 0.5 ) { vol.status == :available }
-          vol.attach_to( inst, "/dev/sdh#{i+1}" ) #=> Attachment
+          ap = if opts[ :ebs_mounts ] == :sdf_p
+                 "/dev/sd" + "fghijklmnop"[i]
+               else
+                 "/dev/sdh#{i+1}"
+               end
+          vol.attach_to( inst, ap ) #=> Attachment
         end
 
         wait_until( "volumes to attach" ) do

data/lib/syncwrap/base.rb

@@ -15,7 +15,7 @@
 #++
 
 module SyncWrap
-  VERSION='2.1.3'
+  VERSION='2.2.0'
 
   GEM_ROOT = File.dirname(File.dirname(File.dirname(__FILE__))) # :nodoc:
 end

data/lib/syncwrap/component.rb

@@ -172,6 +172,10 @@ module SyncWrap
     # :error::      Pass bash the -e option to terminate early on errors.
     #               Default: true
     #
+    # :pipefail::   Pass bash the "-o pipefail" option to return the first
+    #               non-zero command return from a pipeline.
+    #               Default: true when :error is true
+    #
     # :close::      An additional bash fragment to append after the
     #               provided shell command/fragment and block has been
     #               enqueued. See usage example above. Default: nil

data/lib/syncwrap/components/cruby_vm.rb

@@ -45,7 +45,7 @@ module SyncWrap
     # The ruby version to install, as it appears in source packages
     # from ruby-lang.org. Note that starting with 2.1.0, the patch
     # release (p#) no longer appears in package names.
-    # (Default: 2.0.0-p481)
+    # (Default: 2.1.2)
     #
     # Example values: '2.0.0-p481', '2.1.2'
     attr_accessor :ruby_version
@@ -56,7 +56,7 @@ module SyncWrap
     attr_accessor :do_uninstall_distro_ruby
 
     def initialize( opts = {} )
-      @ruby_version = "2.0.0-p481"
+      @ruby_version = "2.1.2"
       @do_uninstall_distro_ruby = true
 
       super

data/lib/syncwrap/components/hashdot.rb

@@ -16,6 +16,9 @@
 
 require 'syncwrap/component'
 
+# For distro class comparison only (pre-load for safety)
+require 'syncwrap/components/ubuntu'
+
 module SyncWrap
 
   # Provision the {Hashdot}[http://hashdot.sourceforge.net/] JVM/script
@@ -59,14 +62,21 @@ module SyncWrap
     end
 
     def install_system_deps
-      dist_install( %w[ make gcc apr apr-devel ] )
+      deps = %w[ make gcc ]
+      deps += if distro.is_a?( Ubuntu )
+                %w[ libapr1 libapr1-dev ]
+              else
+                %w[ apr apr-devel ]
+              end
+
+      dist_install( *deps )
     end
 
     def test_hashdot_binary
       binary = "#{local_root}/bin/hashdot"
       code,_ = capture( <<-SH, accept: [0,91,92] )
         if [ -x #{binary} ]; then
-          cver=`#{binary} 2>&1 | grep -o -E '([0-9]\.?){2,}'`
+          cver=`(#{binary} 2>&1 || true) | grep -o -E '([0-9]\.?){2,}'`
           if [ "$cver" = "#{hashdot_version}" ]; then
             exit 0
           fi

data/lib/syncwrap/components/jruby_vm.rb

@@ -27,11 +27,11 @@ module SyncWrap
   class JRubyVM < Component
     include RubySupport
 
-    # JRuby version to install (default: 1.7.10)
+    # JRuby version to install (default: 1.7.13)
     attr_accessor :jruby_version
 
     def initialize( opts = {} )
-      @jruby_version = '1.7.10'
+      @jruby_version = '1.7.13'
 
       super( { gem_command: 'jgem' }.merge( opts ) )
     end

data/lib/syncwrap/components/postgresql.rb

@@ -22,45 +22,132 @@ require 'syncwrap/components/ubuntu'
 
 module SyncWrap
 
-  # Provisions for install and configuration of PostgreSQL
+  # Provisions for install and configuration of a \PostgreSQL server
   #
   # Host component dependencies: <Distro>
   class PostgreSQL < Component
 
-    # Location of postgresql data dir
-    attr_accessor :pg_data_dir
+    # \PostgreSQL _MAJOR.MINOR_ version to install. Since there are
+    # multiple versions in use even for _default_ system packages across
+    # distros, this should be set the same as the version that will
+    # be installed via #package_names.  (Default: '9.1')
+    attr_accessor :version
 
-    # The distro default data dir (set if known to be different than
-    # distro-specific default, nil -> computed in accessor)
-    attr_writer :pg_default_data_dir
+    # Return #version as an Array of Integer values
+    def version_a
+      @version.split('.').map( &:to_i )
+    end
 
-    def initialize( opts = {} )
-      @pg_data_dir = '/pg/data'
-      @pg_default_data_dir = nil
-      super
+    # Location of postgresql data (and possibly also config) directory.
+    # (Default: #pg_default_data_dir)
+    attr_accessor :pg_data_dir
+
+    def pg_data_dir
+      @pg_data_dir || pg_default_data_dir
     end
 
+    protected
+
+    # The _default_ data dir as used by the distro #package_names.
+    # (Default: as per RHEL or Ubuntu distro packages)
+    attr_writer :pg_default_data_dir
+
     def pg_default_data_dir
       @pg_default_data_dir ||
         case distro
         when RHEL
           '/var/lib/pgsql9/data'
         when Ubuntu
-          '/var/lib/postgresql/9.1/main'
+          "/var/lib/postgresql/#{version}/main"
         else
           raise ContextError, "Distro #{distro.class.name} not supported"
         end
     end
 
-    def pg_deploy_config
-      case distro
-      when RHEL
-        'postgresql/rhel'
-      when Ubuntu
-        'postgresql/ubuntu'
-      else
-        raise ContextError, "Distro #{distro.class.name} not supported"
-      end
+    # Configuration in the '/etc' directory root?
+    # (Default: true on Ubuntu only, per distro package defaults)
+    attr_writer :pg_specify_etc_config
+
+    def pg_specify_etc_config
+      @pg_specify_etc_config || distro.is_a?( Ubuntu )
+    end
+
+    # The package names, including \PostgreSQL server of the
+    # desired version to install.
+    # (Default: Ubuntu: postgresql-_version_; RHEL: postgresql-server)
+    attr_writer :package_names
+
+    def package_names
+      ( @package_names ||
+        ( distro.is_a?( Ubuntu ) && [ "postgresql-#{version}" ] ) ||
+        [ "postgresql-server" ] )
+    end
+
+    # The service name of the \PostgreSQL server to start
+    # (Default: 'postgresql' )
+    attr_accessor :service_name
+
+    # Synchronization level for commit
+    # :off may be desirable on high-latency storage (i.e. EBS), at
+    # increased risk. (PG Default: :on)
+    attr_accessor :synchronous_commit
+
+    # Commit delay in microseconds
+    # 10000 or more may be desirable on high-latency storage, at
+    # increased risk. (PG Default: 0 -> none)
+    attr_accessor :commit_delay
+
+    # WAL log segments (16MB each) (PG Default: 3)
+    attr_accessor :checkpoint_segments
+
+    # Shared buffers (Default: '256MB' vs PG: '128MB')
+    attr_accessor :shared_buffers
+
+    # Work memory (Default: '128MB' vs PG: '1MB')
+    attr_accessor :work_mem
+
+    # Maintenance work memory (Default: '128MB' vs PG: '16MB')
+    attr_accessor :maintenance_work_mem
+
+    # Maximum stack depth (Default: '4MB' vs PG: '2MB')
+    attr_accessor :max_stack_depth
+
+    # Concurrent disk I/O operations
+    # May help to use RAID device count or similar (PG Default: 1)
+    attr_accessor :effective_io_concurrency
+
+    # Method used in pg_hba.conf for local (unix socket) access
+    # (PG Default: :peer)
+    attr_accessor :local_access
+
+    # Method used in pg_hba.conf for local network access. Note
+    # that :peer does not work here.
+    # (PG Default: :md5)
+    attr_accessor :local_network_access
+
+    # Method used in pg_hba.conf for network access
+    # :md5 is a common value for password auth.
+    # If truthy, will also set listen_address = '*' in postgresql.conf
+    # (PG Default: false -> no access)
+    attr_accessor :network_access
+
+    # IPv4 address mask for #network_access
+    # (PG Default: nil -> no IPv4 access)
+    attr_accessor :network_v4_mask
+
+    # IPv6 address mask for #network_access
+    # (PG Default: nil -> no IPv4 access)
+    attr_accessor :network_v6_mask
+
+    # Kernel SHMMAX (Shared Memory Maximum) setting to apply.
+    # Note that PostgreSQL 9.3 uses mmap and should not need this.
+    # Currently this is only set on Ubuntu (RHEL packages take care of
+    # it?) (Default: 300MB if #version < 9.3)
+    attr_writer :shared_memory_max
+
+    def shared_memory_max
+      @shared_memory_max ||
+        ( ( (version_a <=> [9,3]) < 0 ) && 300_000_000 )
     end
 
     def pg_config_dir
@@ -68,12 +155,40 @@ module SyncWrap
       when RHEL
         pg_data_dir
       when Ubuntu
-        '/etc/postgresql/9.1/main'
+        "/etc/postgresql/#{version}/main"
       else
         raise ContextError, "Distro #{distro.class.name} not supported"
       end
     end
 
+    public
+
+    def initialize( opts = {} )
+      @pg_data_dir = nil
+      @pg_default_data_dir = nil
+      @version = '9.1'
+      @package_names = nil
+      @service_name = 'postgresql'
+      @synchronous_commit = :on
+      @commit_delay = 0
+      @checkpoint_segments = 3
+      @shared_buffers = '256MB'
+      @work_mem = '128MB'
+      @maintenance_work_mem = '128MB'
+      @max_stack_depth = '4MB'
+      @effective_io_concurrency = 1
+      @local_access = :peer
+      @local_network_access = :md5
+      @network_access = false
+      @network_v4_mask = nil
+      @network_v6_mask = nil
+      @shared_memory_max = nil
+      super
+    end
+
+    # Calls in order: #package_install, #setup_data_dir, and
+    # #pg_configure then ensures the server is running (via #pg_start) or
+    # is restarted (via #pg_restart) if there were configuration changes.
     def install
       package_install
       changes = setup_data_dir
@@ -83,17 +198,24 @@ module SyncWrap
       else
         pg_restart
       end
+      changes
     end
 
+    # Install the #package_names. In the Ubuntu case, also install any
+    # #shared_memory_max adjustment and stops the server for subsequent
+    # reconfigure or data relocation.
     def package_install
-      dist_install 'postgresql'
+      dist_install( *package_names )
       if distro.is_a?( Ubuntu )
         pg_stop
-        rput( 'etc/sysctl.d/61-postgresql-shm.conf', :user => 'root' )
-        sudo "sysctl -p /etc/sysctl.d/61-postgresql-shm.conf"
+        if shared_memory_max
+          rput( 'etc/sysctl.d/61-postgresql-shm.conf', user: :root )
+          sudo "sysctl -p /etc/sysctl.d/61-postgresql-shm.conf"
+        end
       end
     end
 
+    # Initialize or move the server data directory as per #pg_data_dir.
     def setup_data_dir
       changes = []
 
@@ -101,20 +223,16 @@ module SyncWrap
 
       when RHEL
         unless pg_data_dir == pg_default_data_dir
-          changes = rput( 'etc/sysconfig/pgsql/postgresql', :user => 'root' )
+          changes = rput( 'etc/sysconfig/pgsql/postgresql', user: :root )
         end
 
         sudo( "if [ ! -d '#{pg_data_dir}/base' ]; then", close: "fi" ) do
-          unless pg_data_dir == pg_default_data_dir
-            # (Per Amazon Linux)
-            # Install PGDATA var override for init.d/postgresql
-            sudo <<-SH
-              mkdir -p #{pg_data_dir}
-              chown postgres:postgres #{pg_data_dir}
-              chmod 700 #{pg_data_dir}
-            SH
-          end
-          dist_service( 'postgresql', 'initdb' )
+          sudo <<-SH
+            mkdir -p #{pg_data_dir}
+            chown postgres:postgres #{pg_data_dir}
+            chmod 700 #{pg_data_dir}
+          SH
+          dist_service( service_name, 'initdb' )
         end
 
       when Ubuntu
@@ -133,25 +251,27 @@ module SyncWrap
       changes
     end
 
-    # Update PostgreSQL config files
+    # Update the \PostgreSQL configuration files
     def pg_configure
-      changes = rput( "#{pg_deploy_config}/", pg_config_dir, :user => 'postgres' )
-      if !changes.empty? && pg_config_dir == pg_data_dir
-        sudo( "chmod 700 #{pg_data_dir}" )
-      end
-      changes
+      files  = %w[ pg_hba.conf pg_ident.conf postgresql.conf ]
+      files += %w[ environment pg_ctl.conf ] if distro.is_a?( Ubuntu )
+      files  = files.map { |f| File.join( 'postgresql', f ) }
+      rput( *files, pg_config_dir, user: 'postgres' )
     end
 
+    # Start the server
     def pg_start
-      dist_service( 'postgresql', 'start' )
+      dist_service( service_name, 'start' )
     end
 
+    # Restart the server
     def pg_restart
-      dist_service( 'postgresql', 'restart' )
+      dist_service( service_name, 'restart' )
     end
 
+    # Stop the server
     def pg_stop
-      dist_service( 'postgresql', 'stop' )
+      dist_service( service_name, 'stop' )
     end
 
   end

data/lib/syncwrap/components/rhel.rb

@@ -27,20 +27,18 @@ module SyncWrap
 
     def initialize( opts = {} )
       super
-
-      packages_map.merge!( 'emacs' => 'emacs-nox',
-                           'postgresql' => 'postgresql-server' )
     end
 
-    # Install packages.
-    # A trailing hash is interpreted as options, see below.
+    # Install the specified package names. A trailing hash is
+    # interpreted as options, see below.
     #
     # ==== Options
     # :succeed:: Always succeed (useful for local rpm files which
-    # might already be installed.)
+    #            might already be installed.)
+    #
+    # Other options will be ignored.
     def dist_install( *pkgs )
       opts = pkgs.last.is_a?( Hash ) && pkgs.pop || {}
-      pkgs = dist_map_packages( pkgs )
 
       if opts[ :succeed ]
         sudo "yum install -q -y #{pkgs.join( ' ' )} || true"
@@ -49,19 +47,23 @@ module SyncWrap
       end
     end
 
+    # Uninstall the specified package names.
     def dist_uninstall( *pkgs )
-      pkgs = dist_map_packages( pkgs )
       sudo "yum remove -q -y #{pkgs.join( ' ' )}"
     end
 
+    # Install a System V style init.d service script
     def dist_install_init_service( name )
       sudo "/sbin/chkconfig --add #{name}"
     end
 
+    # Enable the System V style init.d service
     def dist_enable_init_service( name )
       sudo "/sbin/chkconfig #{name} on"
     end
 
+    # Run via sudo, the service command typically supporting 'start',
+    # 'stop', 'restart', 'status', etc. arguments.
     def dist_service( *args )
       sudo( [ '/sbin/service', *args ].join( ' ' ) )
     end

data/lib/syncwrap/components/run_user.rb

@@ -37,11 +37,11 @@ module SyncWrap
     end
 
     # Home directory for the #run_user
-    # (default: nil -> unspecified)
+    # (default: nil -> same as #run_dir)
     attr_writer :run_user_home
 
     def run_user_home
-      @run_user_home
+      @run_user_home || run_dir
     end
 
     def initialize( opts = {} )
@@ -60,10 +60,10 @@ module SyncWrap
     # Create run_user if not already present
     def create_run_user
       sudo( "if ! id #{run_user} >/dev/null 2>&1; then", close: "fi" ) do
-        user_opts  = "-c 'Run User' -s /bin/bash"
+        user_opts  = "-r -c 'Run User' -s /bin/bash"
         user_opts += " -d #{run_user_home}" if run_user_home
         if run_group && run_group != run_user
-          sudo "groupadd -f #{run_group}"
+          sudo "groupadd -r -f #{run_group}"
           user_opts += " -g #{run_group}"
         end
         sudo "useradd #{user_opts} #{run_user}"

data/lib/syncwrap/components/ubuntu.rb

@@ -19,46 +19,48 @@ require 'syncwrap/distro'
 
 module SyncWrap
 
-  # Customizations for Ubuntu and possibly other Debian/apt packaged
+  # Customizations for \Ubuntu and possibly other Debian/apt packaged
   # derivatives. Specific distros/versions may further specialize.
   class Ubuntu < Component
     include SyncWrap::Distro
 
     def initialize( opts = {} )
       super
-
-      packages_map.merge!( 'apr'       => 'libapr1',
-                           'apr-devel' => 'libapr1-dev' )
     end
 
-    # Install packages. The first time this is applied to any given
-    # host, an "apt-get update" is issued as well.  A trailing hash is
-    # interpreted as options, see below.
+    # Install the specified package names. The first time this is
+    # applied to any given host, an "apt-get update" is issued as
+    # well.  A trailing hash is interpreted as options, see below.
     #
     # ==== Options
     # :minimal:: Eqv to --no-install-recommends
+    #
+    # Other options will be ignored.
     def dist_install( *args )
       opts = args.last.is_a?( Hash ) && args.pop || {}
-      args = dist_map_packages( args )
       args.unshift "--no-install-recommends" if opts[ :minimal ]
 
       sudo( "apt-get -yqq update" ) if first_apt?
       sudo( "apt-get -yq install #{args.join ' '}" )
     end
 
+    # Uninstall the specified package names.
     def dist_uninstall( *pkgs )
-      pkgs = dist_map_packages( pkgs )
       sudo "aptitude -yq purge #{pkgs.join ' '}"
     end
 
+    # Install a System V style init.d service script
     def dist_install_init_service( name )
       sudo "/usr/sbin/update-rc.d #{name} defaults"
     end
 
+    # Enable the System V style init.d service
     def dist_enable_init_service( name )
       sudo "/usr/sbin/update-rc.d #{name} enable"
     end
 
+    # Run via sudo, the service command typically supporting 'start',
+    # 'stop', 'restart', 'status', etc. arguments.
     def dist_service( *args )
       sudo( [ '/usr/sbin/service', *args ].join( ' ' ) )
     end