machinery-tool 1.21.0 → 1.22.0

data/manual/docs/machinery-move.1.md

@@ -1,28 +1,24 @@
-
 # move — Move System Description
 
-## SYNOPSIS
+## Synopsis
 
 `machinery move`
     FROM_NAME TO_NAME
 
 `machinery` help move
 
-
-## DESCRIPTION
+## Description
 
 The `move` command renames a stored system description from `FROM_NAME` to `TO_NAME`.
 
-
-## ARGUMENTS
+## Arguments
   * `FROM_NAME` (required):
     Current name of the system description.
 
   * `TO_NAME` (required):
     New name of the system description.
 
-
-## EXAMPLES
+## Examples
 
   * Rename the system description `earth` to `moon`:
 

data/manual/docs/machinery-remove.1.md

@@ -1,20 +1,17 @@
-
 # remove — Remove System Descriptions
 
-## SYNOPSIS
+## Synopsis
 
 `machinery remove` [--all]
     [NAME[,NAME2[,NAME3]]]
 
 `machinery` help remove
 
-
-## DESCRIPTION
+## Description
 
 The `remove` command removes all specified system descriptions.
 
-
-## OPTIONS
+## Options
 
   * `--all` (optional):
     Remove all stored system descriptions.
@@ -22,14 +19,12 @@ The `remove` command removes all specified system descriptions.
   * `--verbose` (optional):
     Explain what is being done.
 
-
-## ARGUMENTS
+## Arguments
 
   * `NAME...` (required):
     Remove specified system descriptions.
 
-
-## EXAMPLES
+## Examples
 
   * Remove the system description stored as `earth`:
 

data/manual/docs/machinery-serve.1.md

@@ -1,14 +1,12 @@
+# serve — Serve System Descriptions Using a Web Server
 
-# serve — Serve System Descriptions Using A Web Server
-
-## SYNOPSIS
+## Synopsis
 
 `machinery serve` [-p PORT | --port=PORT] [--public]
 
 `machinery` help serve
 
-
-## DESCRIPTION
+## Description
 
 The `serve` command spawns a web server to view system descriptions as an HTML
 view.
@@ -20,8 +18,7 @@ Specific descriptions are available from http://127.0.0.1:7585/NAME, where NAME
 is the name of the system description. If no name is specified in the URL an
 overview of all descriptions is served.
 
-
-## OPTIONS
+## Options
 
   * `-p PORT`, `--port=PORT` (optional):
     Specify the port on which the web server will serve the HTML view: Default: 7585
@@ -33,8 +30,7 @@ overview of all descriptions is served.
     Specifying this option, lets the server listen on each configured IP address. By default
     the server will only listen on the localhost IP address 127.0.0.1
 
-
-## EXAMPLES
+## Examples
 
   * Start the server with default options:
 

data/manual/docs/machinery-show.1.md

@@ -1,38 +1,34 @@
-
 # show — Show System Description
 
-## SYNOPSIS
+## Synopsis
 
 `machinery show` [-s SCOPE | --scope=SCOPE] [-e IGNORE-SCOPE | --ignore-scope=IGNORE-SCOPE] [--no-pager] [--show-diffs] [--html] NAME
 
 `machinery` help show
 
-
-## DESCRIPTION
+## Description
 
 The `show` command displays a stored system description.
 Scopes are supported and limit the output to the given scope.
 The hostname of the inspected system and the last modification
 in local time are shown in the title of each scope section.
 
-
-## ARGUMENTS
+## Arguments
 
   * `NAME` (required):
     Use specified system description.
 
-
-## OPTIONS
+## Options
 
   * `-s SCOPE`, `--scope=SCOPE` (optional):
     Limit output to the specified scope.
-    See the [Scope section](#Scopes) for more information.
+    See the [Scope section](machinery_main_scopes.1/) for more information.
     If displaying information related to a scope fails, `show` will print an error message what has failed.
     In case of an error, no content is displayed.
 
   * `-e IGNORE-SCOPE`, `--ignore-scope=IGNORE-SCOPE` (optional):
     Skip output of the specified scope.
-    See the [Scope section](#Scopes) for more information.
+    See the [Scope section](machinery_main_scopes.1/) for more information.
 
   * `--no-pager` (optional):
     Do not pipe output into a pager.
@@ -48,7 +44,7 @@ in local time are shown in the title of each scope section.
   * `--verbose` (optional):
     Display the filters which were applied before showing the system description.
 
-## EXAMPLES
+## Examples
 
   * Show the system description taken from the last inspection, saved as `earth`:
 

data/manual/docs/machinery-upgrade-format.1.md

@@ -1,7 +1,6 @@
-
 # upgrade-format — Upgrade System Description
 
-## SYNOPSIS
+## Synopsis
 
 `machinery upgrade-format` --all
 
@@ -9,8 +8,7 @@
 
 `machinery` help upgrade-format
 
-
-## DESCRIPTION
+## Description
 
 The `upgrade-format` command upgrades a system description to the latest format
 version.
@@ -24,19 +22,17 @@ in the `meta` section of the according `manifest.json` file.
 
 If the `--all` switch is given all local descriptions will be upgraded.
 
-
-## OPTIONS
+## Options
 
   * `--all` (optional):
     Upgrade all stored system descriptions.
 
-## ARGUMENTS
+## Arguments
 
   * `NAME` (optional):
     Upgrade specified system description.
 
-
-## EXAMPLES
+## Examples
 
   * Upgrade the system description stored as `earth`:
 

data/manual/docs/machinery-validate.1.md

@@ -1,14 +1,12 @@
-
 # validate — Validate System Description
 
-## SYNOPSIS
+## Synopsis
 
 `machinery validate` NAME
 
 `machinery` help validate
 
-
-## DESCRIPTION
+## Description
 
 The `validate` subcommand validates an existing system description.
 It checks, that the description has the correct structure and the data stored
@@ -20,14 +18,12 @@ In case of issues errors are shown with additional information.
 The main purpose of this command is to verify the system description after
 manually editing it.
 
-
-## ARGUMENTS
+## Arguments
 
   * `NAME` (required):
     Name of the system description.
 
-
-## EXAMPLES
+## Examples
 
  * Validate the system description with the name `myhost`:
 

data/manual/docs/machinery_main_general.1.md

@@ -1,50 +1,11 @@
 # Machinery — A Systems Management Toolkit for Linux
 
-# SYNOPSIS
+# Synopsis
 
 `machinery` SUBCOMMAND \[options\] <br>
 `machinery` help [SUBCOMMAND]
 
-
-# DESCRIPTION
-
-Machinery is a systems management toolkit for Linux. It supports configuration
-discovery, system validation, and service migration. Machinery is based on the
-idea of an universal system description. Machinery has a set of commands which
-work with this system description. These commands can be combined to form work
-flows. Machinery is targeted at the system administrator of the data center.
-
-
-# WORK FLOW EXAMPLES
-
-## Inspect a System and Show Results
-  - `machinery inspect --extract-files --name=NAME HOSTNAME`
-  - `machinery show NAME`
-
-## Inspect Two Systems and Compare Them
-  - `machinery inspect HOSTNAME1`
-  - `machinery inspect HOSTNAME2`
-  - `machinery compare HOSTNAME1 HOSTNAME2`
-
-## Fully Inspect a System and Export a Kiwi Description
-  - `machinery inspect --extract-files HOSTNAME`
-  - `machinery export-kiwi --kiwi-dir=~/kiwi HOSTNAME`
-
-## Fully Inspect a System and Export an AutoYaST Profile
-  - `machinery inspect --extract-files HOSTNAME`
-  - `machinery export-autoyast --autoyast-dir=~/autoyast HOSTNAME`
-
-## Fully Inspect a System and Deploy a Replicate to the Cloud
-  - `machinery inspect --extract-files HOSTNAME`
-  - `machinery deploy --cloud-config=~/openrc.sh HOSTNAME`
-
-## How to upgrade a SLES 11 SP3 system to SLES 12
-  - Machinery can help you to upgrade without affecting the original system.
-    For more details please read the Wiki Page: <br>
-    https://github.com/SUSE/machinery/wiki/How-to-upgrade-a-SLES-11-SP3-system-to-SLES-12
-
-
-# CONCEPTUAL OVERVIEW
+# Conceptual Overview
 
 Machinery's core concept is the complete representation of a system by a
 universal system description.
@@ -55,7 +16,7 @@ modifications.
 Machinery's subcommands work on the system description as the connecting
 element.
 System descriptions are obtained by inspecting systems, importing from other
-formats, manual creation or merging other descriptions.
+formats, manual creation or merging existing descriptions.
 Machinery can store and modify system descriptions to allow changes to
 described state of the system.
 System descriptions can be compared to find similarities and differences
@@ -64,7 +25,7 @@ the system.
 System descriptions may be exported to other formats and can be used to
 migrate or replicate systems.
 
-Subcommands can be combined in different ways to accomodate higher-level work
+Subcommands can be combined in different ways to accommodate higher-level work
 flows and use cases.
 These are some implemented and planned use cases:
 
@@ -100,6 +61,19 @@ Machinery is implemented as a command line tool named `machinery`. The
 subcommands work with the same system description identified by an optional
 name which can be used by all subcommands.
 
+## System Description
+
+The System Description format and file structure is documented in the machinery
+wiki: [System Description Format](https://github.com/SUSE/machinery/wiki/System-Description-Format).
+
+Machinery validates descriptions on load. It checks that the JSON structure of
+the manifest file, which contains the primary and meta data of a description, is 
+correct and it adheres to the schema. Validation errors are reported as warnings.
+It also checks that the information about extracted files is consistent. Missing
+files or extra files without reference in the manifest are treated also as
+warnings. All other issues are errors which need to be fixed so that Machinery
+can use the description.
+To manually validate a description use the `machinery validate` command.
 
 ## Scopes
 
@@ -110,9 +84,19 @@ repositories, or changed configuration files.
 For example, if you are only interested in the installed packages, limit the
 scope to `packages`. This will output only the requested information.
 
-The the [scopes documentation](machinery_main_scopes.1) for a list of all supported scopes.
+See the [Scopes documentation](machinery_main_scopes.1/) for a list of all supported scopes.
+
+# Options for All Subcommands
+<!--- These are 'global' options of machinery -->
 
-# FILES AND DEVICES
+  * `--version`:
+    Displays version of `machinery` tool. Exit when done.
+
+  * `--debug`:
+    Enable debug mode. Machinery writes additional information into the log
+    file which can be useful to track down problems.
+
+# Files and Devices
 
   * `~/.machinery/machinery.config`:
 
@@ -122,18 +106,16 @@ The the [scopes documentation](machinery_main_scopes.1) for a list of all suppor
 
     Central log file, in the format date, time, process id, and log message.
 
-  * `eth0` (SLE11) and `lan0` (SLE12):
+  * `em1 (openSUSE 13.2 / openSUSE leap)`, `eth0` (SLE11) and `lan0` (SLE12):
 
     First network device is used when DHCP in built image is enabled.
 
-
-# ENVIRONMENT
+# Environment
 
   * `MACHINERY_LOG_FILE`:
 
-    Location of Machinery's log file (defaults to `~/.machinery/machinery.log`)
-
+    Location of Machinery's log file (defaults to `~/.machinery/machinery.log`).
 
-# COPYRIGHT
+# Copyright
 
 Copyright \(c) 2013-2016 [SUSE LLC](http://www.suse.com)

data/manual/docs/machinery_main_scopes.1.md

@@ -1,3 +1,5 @@
+# Scopes
+
 * os
 
 Contains information about the operating system, name, version, and
@@ -5,25 +7,22 @@ architecture of the inspected system.
 
 * packages
 
-Contains information on all installed RPM packages installed on the
+Contains information on all installed packages installed on the
 inspected system.
 
 * patterns
 
 Contains all patterns or tasks installed on the inspected system. A pattern is a
 collection of software packages, similar to the idea of tasks on Debian/Ubuntu-
-like systems.
-The meaning of software patterns depends on the package manager of the
-distribution. Therefore, the pattern scope on SUSE based systems uses the
-`zypper` command to obtain the information about installed pattern names, whereas
-on Debian based systems the `tasksel` tool is necessary to list installed tasks.
+like systems. The meaning of software patterns depends on the package manager of the
+distribution.
 
 * repositories
 
 Contains all information about software repositories configured on the
 inspected system. The information about repositories depends on the package
-manager of the distribution. Thus on SUSE-based systems the `zypper` command
-is used. Machinery collects the following information from each configured repository:
+manager of the distribution. Machinery collects the following information
+from each configured repository:
 
 - The alias name of the repository.
 
@@ -65,7 +64,7 @@ runlevel. It uses the `chkconfig` command to obtain that information.
 The xinetd services that are also displayed by `chkconfig` are switched
 on/off by editing configuration files and are ignored in this context.
 
-* changed_config_files
+* changed-config-files
 
 Contains all configuration files which have been changed since they were
 installed.
@@ -74,22 +73,22 @@ package which has installed them. A configuration file change is reported
 if its content or its attributes like Linux permission bits or ownership
 have changed.
 
-* changed_managed_files
+* changed-managed-files
 
 Contains the names and contents of all non-configuration files which have
 been changed compared to the files in the package. A file change is reported
 if its content or its attributes like Linux permission bits or ownership
 have changed.
 
-* unmanaged_files
+* unmanaged-files
 
-Contains the names and contents of all files which are not part of any RPM
-package. The list of unmanaged files contains only plain files and
+Contains the names and contents of all files which are not part of any package.
+The list of unmanaged files contains only plain files and
 directories. Special files like device nodes, named pipes and Unix domain
 sockets are ignored. The directories `/tmp`,  `/var/tmp`, `/.snapshots/`,
 `/var/run` and special mounts like procfs and sysfs are ignored, too.
 If a directory is in this list, no file or directory below it belongs to a
-RPM package.
+package.
 
 Meta data information of unmanaged files is only available if the files were
 extracted during inspection.