tweek 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1e291275563c2896f9c59ee25c11486e0a891f7
-  data.tar.gz: e97cac8c95c5beda3dc9ec48a3c4ea418c5d6bbc
+  metadata.gz: 597134731238b0b8b85cff135316ba1583820159
+  data.tar.gz: 5f6817a52a96db1a1cf6fef2ba90657699c637ac
 SHA512:
-  metadata.gz: 49c42da3fcfa156d2f12cd6fdf561fb2a010982f7e272ec45ec00d49f7f829021606cd8f26bd78679791ad8c58125ff360118ce2a9a5a69890b7c9432ea6e59e
-  data.tar.gz: b2c84d89a856596c074c941e757d047b902877a4a4ad513ca0b22e42bc88fb4f196b0140e9fd0cb4aececd9200f3a746648899520c3fa8c345a36b5080f1fc8e
+  metadata.gz: 8c2a6e275f98ec45e9faa64317e75894d41100ccfd6ad746d94eedcf1d81e5123201988182d5f52ee124dd6b9760cec092844286b12b9e43f3fd74d4447e155a
+  data.tar.gz: b074907fdea87694c3f2fd0106f6a3d1ac5aac430c984ae9752a4309c222784cc39d9bdd2f0e70b00b70ef3a4659fe2797800a1a88be070d424d4f643ce1a0bc

data/README.md

@@ -19,12 +19,16 @@ user to check obscure settings without actually knowing the commands needed.
 One of the objectives of the Tweek GitHub repository is to serve as a repository for sets
 of configuration parameters that have been found by the community to be useful in
 maximizing performance for certain machines and workloads. It is hoped people will submit
-pull requests to add settings files to the `settings` subdirectory of this project.
+pull requests to add settings files to the `settings` subdirectory of this project. These
+can then be referenced directly using URLs, or downloaded locally then edited to suit
+prior to running.
 
 ## Installation
 
-Tweek has been written to use Ruby 1.8.7 or above which is available on all Linux systems
-within the last five years or so. It also requires `rubygems`.
+Tweek requires use Ruby 1.8.7 or above and so can be used on all Linux systems
+within the last five years or so.
+
+When using Ruby 1.8.7 note that using settings file via `https` URLs can be problematic.
 
 ### Do I need to be the 'root' user?
 
@@ -49,43 +53,34 @@ successful. You should now be able to type `tweek -?` to see the available optio
 
 ## Usage
 
-Tweek can be used in the following modes:
-
- * To check the current system against a default configuration
- * To create a sample settings file that you can edit manually
- * To generate a settings file based on the current system configuration
- * To check the current system configuration against a file of settings.
- * To set the current system configuration to a file of settings.<br>
-   __NOTE__ this is currently restricted to `sysctl` parameters only. TBD.
-
-In the first case Tweek uses a built-in set of defaults. To check using these simply run:
-
-```
-tweek
-```
+Tweek can be used in several ways:
 
-Tweek will read the sample settings from the default file `settings/sample.set` (which is
-installed as part of the Gem) and check them. The output is self-explanatory.
+ * To create a sample settings file that you can edit manually,
+ * To check the current system against a desired configuration embodied in a file of settings,
+ * To set or reset the current system configuration to a file of settings.<br>
+   __NOTE__ set/reset is currently restricted to `sysctl` parameters only. TBD.
 
-All the other uses involve the settings file. Documentation is contained within the
-sample settings and you should read them for a full understanding of what is possible.
-Use `tweek -s` to show them.
+The settings file can be local or remote (using a variety of URL formats). It has a simple text format
+which is fully documented in a sample file that can be generated using `tweek -s`.
 
 ### Output
 
 The output of Tweek is controlled by the `output` option, which takes the following
 values (default `1`):
 
-0. No output, just a return code.
+0. No output, just a return code.<br>
+   Useful when using `pssh` or `mush` to execute on multiple machines.
 
-1. Summary output only is written to STDERR. It consists of a string of dots (when a
-   parameter is OK) or the letter 'F' (when a parameter doesn't match) followed by a
-   summary line.
+1. Summary output only is written to STDERR.<br>
+   It consists of a string of dots (when a parameter is OK) or the letter 'F'
+   (when a parameter doesn't match) or the letter 's'
+   (when a parameter is skipped due to failing a condition check), followed by a summary line.
 
-2. Only the settings that didn't match are written to STDOUT in a form that can be reused
-   as input. The summary is written to STDERR
+2. The summary is written to STDERR.<br>
+   Only the settings that **didn't** match are written to STDOUT in a form that can be reused as input.
 
-3. All the settings are written to STDOUT in a form that can be reused as input.
+3. The summary is written to STDERR.<br>
+   **All** the settings are written to STDOUT in a form that can be reused as input.
 
 The latter formats differ slightly depending on whether the utility is operating in query
 mode, set mode or reset mode. See below.
@@ -93,7 +88,7 @@ mode, set mode or reset mode. See below.
 Note that the output is colorized by default. Disable this with `--no-color`.
 
 * red: a value that doesn't match or conditions that are not met
-* yellow: expected values
+* yellow: expected or previous values
 * green: conditions that are met
 * bold: emphasis
 
@@ -107,16 +102,16 @@ The actions of Tweek are controlled by the `mode` option, which takes the follow
 <dt>query</dt>
 
 <dd>the settings are checked against the actual values and mismatches are highlighted and
-noted in a comment with the syntax '[expected xxx]'</dd>
+noted in a comment with the syntax <tt>[expected xxx]</tt></dd>
 
 <dt>set</dt>
 
 <dd>the settings are set to the given value, mismatches are highlighted and noted in a
-trailing comment with the syntax '[was xxx]'</dd>
+trailing comment with the syntax <tt>[was xxx]</tt></dd>
 
 <dt>reset</dt>
 
-<dd>action as above but the settings are taken from the '[was xxx]' comments</dd>
+<dd>action as above but the settings are taken from the <tt>[was xxx]</tt> comments</dd>
 
 </dl>
 
@@ -132,7 +127,7 @@ highlighting (using Ruby as the language) makes it very readable.
 ### Comments
 
 Comments are of two sorts:
- * Inline: after the first # on any line
+ * Inline: after the first `#` on any line
  * Block: Following the Ruby convention these begin with `=begin` and end with `=end`
 
 ### Sections
@@ -192,6 +187,48 @@ An example for Redhat 7 is:
 tweek --distro=RedHatEnterpriseServer --distro-ver=7.4 --kernel-ver=3.10.0
 ```
 
+## Example
+
+Given the following input file `sysctl.twk`:
+
+```text
+# Sample test file
+
+SYSCTL
+
+kernel.msgmax = 65536 if k ~> 3.1
+kernel.shmmax = 4000000000 if k>2.5 # Crazy high!
+kernel.shmall = 4294967296
+```
+
+### Querying Current Values
+
+Running the command `tweek -o 3 sysctl.twk` produces the following output:
+
+<a><img src="./query.svg"/></a>
+
+Note that red denotes conditions that weren't met, or values that differed from the
+expected ones. Green denotes conditions that were met, and yellow is used to highlight
+expected values, that are called out in the comments.
+
+### Setting New Values
+
+Running the command `tweek -m s -o 3 sysctl.twk` produces the following output:
+
+<a><img src="./set.svg"/></a>
+
+Note that colors have the same meaning, but now the previous values (if different) are
+recorded in yellow.  You can save this format for use in `reset` mode, if using
+redirection the `--no-color` option removes the ANSI escape sequences.
+
+### Resetting Values
+
+Running the command `tweek -m r -o 3 <above output>` produces the following output:
+
+<a><img src="./reset.svg"/></a>
+
+Note that a value will only be reset if it matches!
+
 ## Development
 
 Tweek was developed using the gem `bundler`. Ensure you have both this and `rake` installed using:

data/bin/tweek

@@ -26,8 +26,8 @@ cflag = true
 distro = nil
 distro_ver = nil
 kernel_ver = nil
-OptionParser.new do |o|
-    o.banner = "Usage: #{$0} [options] [settings_file...]"
+optparse = OptionParser.new do |o|
+    o.banner = "Usage: #{$0} [options] settings_files..."
     o.separator ""
     o.separator "Check and/or update the system parameters specified in the settings files"
     o.separator "(If not supplied then built-in samples are used)"
@@ -107,11 +107,8 @@ if kernel_ver.nil?
 end
 cs = Tweek::File.new(distro, distro_ver, kernel_ver, mflag, oflag)
 if ARGV.empty?
-  if mflag != :query
-    STDERR.puts "You can't update the system with the sample settings, specify one or more Tweek files!"
-    exit 2
-  end
-  fh = File.open(File.expand_path('../../settings/sample.twk',__FILE__))
+  STDERR.puts optparse
+  exit 2
 else
   dir = FileUtils.pwd
   ARGV.each do |file|

data/lib/tweek/version.rb

@@ -1,3 +1,3 @@
 module Tweek
-  VERSION = "1.2.1"
+  VERSION = "1.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tweek
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
 platform: ruby
 authors:
 - Nick Townsend
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-14 00:00:00.000000000 Z
+date: 2017-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize