machinery-tool 1.17.0 → 1.18.0

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

@@ -0,0 +1,145 @@
+
+# inspect — Inspect Running System
+
+## SYNOPSIS
+
+`machinery inspect` [OPTIONS] HOSTNAME
+
+`machinery` help inspect
+
+
+## DESCRIPTION
+
+The `inspect` command inspects a running system and generates a system
+description from the gathered data.
+
+The system data is structured into scopes, controlled by the
+`--scope` option.
+
+**Note**:
+Machinery will always inspect all specified scopes, and skip scopes which
+trigger errors.
+
+
+## ARGUMENTS
+
+  * `HOSTNAME` (required):
+    The host name of the system to be inspected. The host name will also be
+    used as the name of the stored system description unless another name is
+    provided with the `--name` option.
+
+
+## OPTIONS
+
+  * `-n NAME`, `--name=NAME` (optional):
+    Store the system description under the specified name.
+
+  * `-s SCOPE`, `--scope=SCOPE` (optional):
+    Inspect system for specified scope.
+    See the [Scope section](machinery_main_scopes.1/index.html) for more information.
+
+  * `-e SCOPE`, `--exclude-scope=EXCLUDE-SCOPE` (optional):
+    Inspect system for all scopes except the specified scope.
+    See the [Scope section](machinery_main_scopes.1/index.html) for more information.
+
+  * `-r USER`, `--remote-user=USER` (optional):
+    Defines the user which is used to access the inspected system via SSH.
+    This user needs to be allowed to run certain commands using sudo (see
+    PREREQUISITES for more information).
+    To change the default-user use `machinery config remote-user=USER`
+
+  * `-p SSH-PORT`, `--ssh-port SSH-PORT` (optional):
+    Specifies the SSH port of the remote SSH server.
+
+  * `-i SSH-IDENTITY-FILE`, `--ssh-identity-file SSH-IDENTITY-FILE` (optional):
+    Specifies the SSH private key what should be used to authenticate with the
+    remote SSH server. Keys with a passphrase are not allowed here. Use the ssh-agent
+    instead.
+
+  * `-x`, `--extract-files` (optional):
+    Extract changed configuration and unmanaged files from the inspected system.
+    Shortcut for the combination of `--extract-changed-config-files`,
+    `--extract-unmanaged-files`, and `--extract-changed-managed-files`
+
+  * `--extract-changed-config-files` (optional):
+    Extract changed configuration files from the inspected system.
+
+  * `--extract-unmanaged-files` (optional):
+    Extract unmanaged files from the inspected system.
+
+  * `--extract-changed-managed-files` (optional):
+    Extract changed managed files from inspected system.
+
+  * `--skip-files` (optional):
+    Do not consider given files or directories during inspection. Either provide
+    one file or directory name or a list of names separated by commas. You can
+    also point to a file which contains a list of files to filter (one per line)
+    by adding an '@' before the path, e.g.
+
+      $ `machinery` inspect --skip-files=@/path/to/filter_file myhost
+
+    If a filename contains a comma it needs to be escaped, e.g.
+
+      $ `machinery` inspect --skip-files=/file\\,with_comma myhost
+
+    **Note**: File or directory names are not expanded, e.g. '../path' is taken
+      literally and not expanded.
+
+  * `--verbose` (optional):
+    Display the filters which are used during inspection.
+
+
+## PREREQUISITES
+
+  * Inspecting a local system requires running `machinery` as root.
+
+  * Inspecting a remote system requires passwordless SSH login as root on the
+    inspected system.
+    Use `ssh-agent` or asymmetric keys (you can transfer the current SSH key
+    via `ssh-copy-id` to the inspected host, e.g.: `ssh-copy-id root@HOSTNAME`)
+
+  * The system to be inspected needs to have the following commands:
+
+    * `rpm` or `dpkg`
+    * `zypper`, `yum`, or `apt-cache`
+    * `rsync`
+    * `chkconfig`, `initctl`, or `systemctl`
+    * `cat`
+    * `sed`
+    * `find`
+    * `tar`
+
+  * When inspecting as non-root the user needs passwordless sudo rights.
+    The following entry in the sudoers file would allow the user `machinery`
+    to run sudo without password input:
+
+      machinery ALL=(ALL) NOPASSWD: ALL
+
+  * To add a remote `machinery` user run as root:
+
+    \# `useradd` -m machinery -c "remote user for machinery"
+
+    To configure a password for the new user run:
+
+    \# `passwd` machinery
+
+## EXAMPLES
+
+  * Inspect remote system `myhost` and save system description under name
+    'MySystem':
+
+    $ `machinery` inspect --name=MySystem myhost
+
+  * Inspect the installed packages of your local system and save system description
+    under the name 'localhost' (you need to become root):
+
+    \# `machinery` inspect --scope="packages" localhost
+
+  * Extracts changed managed files and saves them in the same way as changed
+    configuration files are saved:
+
+    $ `machinery` inspect --scope=changed-managed-files --extract-files myhost
+
+  * To inspect the remote system `myhost` with the user `machinery`:
+
+    $ `machinery` inspect --remote-user machinery myhost

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

@@ -0,0 +1,51 @@
+
+# list — List System Descriptions
+
+## SYNOPSIS
+
+`machinery list` [OPTIONS] [NAME[,NAME2[,NAME3]]]
+
+`machinery` help list
+
+
+## DESCRIPTION
+
+List the specified system descriptions if parameter name is given.
+List all available system descriptions in the internal database if no name parameter is given.
+The list is sorted alphabetically and contains a name and the
+scopes for each system.
+
+
+## OPTIONS
+
+  * `--verbose` (optional):
+    Print additional information about the origin of scopes.
+    Currently displays [HOSTNAME] and (DATE).
+  * `--short` (optional):
+    List only descripton names.
+  * `--html` (optional):
+    Run a web server and open the list of system descriptions in HTML format in
+    your web browser using the `xdg-open` command.
+
+
+## EXAMPLES
+
+  * Lists the two specified system descriptions `a` and `b`:
+
+    $ `machinery` list a b
+
+  * Lists all available system descriptions:
+
+    $ `machinery` list
+
+  * Same as previous command, but additionally prints the date of each scope:
+
+    $ `machinery` list --verbose
+
+  * Lists all available system description names without any additional details:
+
+    $ `machinery` list --short
+
+  * Opens HTML view of list of all available system descriptions in web browser:
+
+    $ `machinery` list --html

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

@@ -0,0 +1,16 @@
+
+# man — Shows Man Page
+
+## SYNOPSIS
+
+  `machinery man` [OPTIONS]
+
+## OPTIONS
+
+  * `--html` (optional):
+    Run a web server and open the documentation in HTML format in your web browser using the
+    `xdg-open` command.
+
+## DESCRIPTION
+
+The `man` command shows the Machinery man page.

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

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

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

@@ -0,0 +1,44 @@
+
+# remove — Remove System Descriptions
+
+## SYNOPSIS
+
+`machinery remove` [--all]
+    [NAME[,NAME2[,NAME3]]]
+
+`machinery` help remove
+
+
+## DESCRIPTION
+
+The `remove` command removes all specified system descriptions.
+
+
+## OPTIONS
+
+  * `--all` (optional):
+    Remove all stored system descriptions.
+
+  * `--verbose` (optional):
+    Explain what is being done.
+
+
+## ARGUMENTS
+
+  * `NAME...` (required):
+    Remove specified system descriptions.
+
+
+## EXAMPLES
+
+  * Remove the system description stored as `earth`:
+
+    $ `machinery` remove earth
+
+  * Remove the system descriptions stored as `earth` and `moon`:
+
+    $ `machinery` remove earth moon
+
+  * Remove all stored system descriptions:
+
+    $ `machinery` remove --all

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

@@ -0,0 +1,45 @@
+
+# serve — Serve System Descriptions Using A Web Server
+
+## SYNOPSIS
+
+`machinery serve` [-p PORT | --port=PORT] [--public]
+
+`machinery` help serve
+
+
+## DESCRIPTION
+
+The `serve` command spawns a web server to view system descriptions as an HTML
+view.
+
+By default the server is available from http://127.0.0.1:7585 but both the
+IP address and the port can be configured using the according options.
+
+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
+
+  * `-p PORT`, `--port=PORT` (optional):
+    Specify the port on which the web server will serve the HTML view: Default: 7585
+
+    Ports can be selected in a range between 2-65535. Ports between 2 and 1023 can only be
+    chosen when `machinery` will be executed as `root` user.
+
+  * `--public` (optional):
+    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
+
+  * Start the server with default options:
+
+    $ `machinery` serve
+
+  * Make the server available to other machines on the network on port 3000:
+
+    $ `machinery` serve --public --port 3000

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

@@ -0,0 +1,63 @@
+
+# show — Show System Description
+
+## SYNOPSIS
+
+`machinery show` [-s SCOPE | --scope=SCOPE] [-e EXCLUDE-SCOPE | --exclude-scope=EXCLUDE-SCOPE] [--no-pager] [--show-diffs] [--html] NAME
+
+`machinery` help show
+
+
+## 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
+
+  * `NAME` (required):
+    Use specified system description.
+
+
+## OPTIONS
+
+  * `-s SCOPE`, `--scope=SCOPE` (optional):
+    Limit output to the specified scope.
+    See the [Scope section](#Scopes) 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 EXCLUDE-SCOPE`, `--exclude-scope=EXCLUDE-SCOPE` (optional):
+    Skip output of the specified scope.
+    See the [Scope section](#Scopes) for more information.
+
+  * `--no-pager` (optional):
+    Do not pipe output into a pager.
+
+  * `--show-diffs` (optional):
+    Include the generated diffs in the output if available (see `machinery help analyze`
+    for more information).
+
+  * `--html` (optional):
+    Run a web server and open the system description in HTML format in your web browser using the
+    `xdg-open` command.
+
+  * `--verbose` (optional):
+    Display the filters which were applied before showing the system description.
+
+## EXAMPLES
+
+  * Show the system description taken from the last inspection, saved as `earth`:
+
+    $ `machinery` show earth
+
+  * Show the system description, but limit the scope to repositories only:
+
+    $ `machinery` show earth -s repositories
+
+  * Show the list of changed managed files:
+
+    $ `machinery` show earth --scope=changed-managed-files

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

@@ -0,0 +1,47 @@
+
+# upgrade-format — Upgrade System Description
+
+## SYNOPSIS
+
+`machinery upgrade-format` --all
+
+`machinery upgrade-format` NAME
+
+`machinery` help upgrade-format
+
+
+## DESCRIPTION
+
+The `upgrade-format` command upgrades a system description to the latest format
+version.
+
+The `format` in this context is the structure of the internal system description
+data. If the format version of a system description does not match the current
+`machinery` format version, `machinery` is no longer able to work with the data
+until it is upgraded. The current format version can be retrieved using
+`machinery --version`. The format version of a system description can be found
+in the `meta` section of the according `manifest.json` file.
+
+If the `--all` switch is given all local descriptions will be upgraded.
+
+
+## OPTIONS
+
+  * `--all` (optional):
+    Upgrade all stored system descriptions.
+
+## ARGUMENTS
+
+  * `NAME` (optional):
+    Upgrade specified system description.
+
+
+## EXAMPLES
+
+  * Upgrade the system description stored as `earth`:
+
+    $ `machinery` upgrade-format earth
+
+  * Upgrade all stored system descriptions:
+
+    $ `machinery` upgrade-format --all