machinery-tool 1.17.0 → 1.18.0

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

@@ -0,0 +1,62 @@
+# build — Build Image from System Description
+
+## SYNOPSIS
+
+`machinery build` NAME -i IMAGE-DIR | --image-dir=IMAGE-DIR
+
+`machinery` help build
+
+
+## DESCRIPTION
+
+The `build` command builds an image from a system description. The image is a
+system image in the qcow2 format, which can be used with the KVM hypervisor.
+It can be run locally or deployed to a cloud environment.
+
+`machinery` uses the image building command line tool
+[KIWI](http://en.opensuse.org/Portal:KIWI) to perform the actual build. KIWI
+data is stored to a temporary directory and cleaned up after the build. The KIWI
+log is shown as output of the `build` command format for showing progress and
+diagnosing errors.
+
+When building an image, Machinery filters out some files which would break the
+built image. The list of filters is shown at the beginning of the build.
+
+
+## ARGUMENTS
+
+  * `NAME` (required):
+    Use specified system description.
+
+
+## OPTIONS
+
+  * `-i IMAGE-DIR`, `--image-dir=IMAGE-DIR` (required):
+    Save image file under specified path.
+
+  * `-d`, `--enable-dhcp` (optional):
+    Enable DHCP client on first network card of built image
+
+  * `-s`, `--enable-ssh` (optional):
+    Enable SSH service in built image
+
+
+## PREREQUISITES
+
+  * The `build` command requires the packages `kiwi` and `kiwi-desc-vmxboot`.
+
+  * The necessary vmxboot template for the machinery being built must be
+    installed (i.e. if you want to build an openSUSE Leap machine then the
+    template `/usr/share/kiwi/image/vmxboot/suse-leap42.1` is required)
+
+  * All repositories in the system description must be accessible from the
+    build machine on which `machinery build` is called.
+
+  * Machinery can only build x86_64 images on x86_64 systems at the moment.
+
+## EXAMPLES
+
+ * To build an image from the system description named "tux" and to save the
+   image under the `/tmp/tux/` directory:
+
+    $ `machinery` build tux -i /tmp/tux/

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

@@ -0,0 +1,63 @@
+
+# compare — Compare System Descriptions
+
+## SYNOPSIS
+
+`machinery compare` [-s SCOPE | --scope=SCOPE] [-e EXCLUDE-SCOPE | --exclude-scope=EXCLUDE-SCOPE] [--no-pager] [--show-all] [--html] NAME1 NAME2
+
+`machinery` help compare
+
+
+## DESCRIPTION
+
+The `compare` command compares stored system descriptions. The scope option can
+be used to limit the output to the given scopes.
+
+
+## ARGUMENTS
+
+  * `NAME1` (required):
+    First system description to compare.
+
+  * `NAME2` (required):
+    Second system description to compare.
+
+
+## OPTIONS
+
+  * `-s SCOPE`, `--scope=SCOPE` (optional):
+    Limit output to the specified scope.
+    See the [Scope section](#Scopes) for more information.
+
+  * `-e 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-all` (optional):
+    Show also common properties of the descriptions (not only the differences).
+
+  * `--html` (optional):
+    Shows the comparison of two system descriptions in the web browser.
+
+
+## EXAMPLES
+
+  * Compare system descriptions saved as `earth` and `moon`:
+
+    $ `machinery` compare earth moon
+
+  * Compare system descriptions, but limit the scope to repositories only:
+
+    $ `machinery` compare earth moon -s repositories
+
+  * Compare lists of changed managed files and include the common ones in the
+    list:
+
+    $ `machinery` compare earth moon --scope=changed-managed-files --show-all
+
+  * Compares system descriptions and shows the result in HTML format in your web browser:
+
+    $ `machinery` compare --html earth moon

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

@@ -0,0 +1,45 @@
+
+# config — Configure Machinery
+
+## SYNOPSIS
+
+`machinery config`
+
+`machinery config` KEY
+
+`machinery config` KEY=VALUE
+
+`machinery` help config
+
+
+## DESCRIPTION
+
+The `config` command shows or changes machinery's configuration.
+
+If no arguments are passed the `config` command lists all configuration
+entries and their values. If only the key is provided its value is shown.
+If key and value are specified this configuration entry is set accordingly.
+
+The configuration is stored in `~/.machinery/machinery.config`.
+
+## ARGUMENTS
+  * `KEY`:
+    Name of the configuration entry.
+
+  * `VALUE`:
+    Value of the configuration entry.
+
+
+## EXAMPLES
+
+  * Turn off hints:
+
+    $ `machinery` config hints=off
+
+  * Show current configuration of hints:
+
+    $ `machinery` config hints
+
+  * List all configuration entries and their values:
+
+    $ `machinery` config

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

@@ -0,0 +1,31 @@
+
+# copy — Copy System Description
+
+## SYNOPSIS
+
+`machinery copy`
+    FROM_NAME TO_NAME
+
+`machinery` help copy
+
+
+## DESCRIPTION
+
+The `copy` command copies a stored system description. It creates a new
+description named TO_NAME containing the same content as the description
+FROM_NAME.
+
+
+## ARGUMENTS
+  * `FROM_NAME` (required):
+    Name of the source system description.
+
+  * `TO_NAME` (required):
+    Name of the target system description.
+
+
+## EXAMPLES
+
+  * Create a copy of the system description `earth` under the name `moon`:
+
+    $ `machinery` copy earth moon

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

@@ -0,0 +1,71 @@
+
+# deploy — Deploy Image to OpenStack Cloud
+
+## SYNOPSIS
+
+`machinery deploy` NAME -c CONFIG_FILE | --cloud-config=CONFIG_FILE
+   [-i IMAGE_DIR | --image-dir=IMAGE_DIR]
+   [-n CLOUD_IMAGE_NAME | --cloud-image-name=CLOUD_IMAGE_NAME]
+   [-s | --insecure ]
+
+`machinery` help [deploy]
+
+
+## DESCRIPTION
+
+The `deploy` command builds and deploys an image to an OpenStack cloud.
+This command is particularly useful for testing, debugging, or for validation.
+
+
+> #### NOTE: Set Password for Unattended Work
+> Machinery asks for a password when sourcing the configuration
+> file. This interrupts the work flow and the user has to enter
+> this password.
+> If you prefer to leave it uninterrupted and unattented, remove
+> the following line in your cloud configuration file (see the `-c` option):
+>
+>   read -s OS_PASSWORD_INPUT
+>
+> and set the password in the `OS_PASSWORD` variable:
+>
+>   export OS_PASSWORD=YOUR_PASSWORD
+
+
+## ARGUMENTS
+
+  * `NAME` (required):
+    Name of the system description.
+
+
+## OPTIONS
+
+  * `-c CONFIG_FILE`, `--cloud-config=CONFIG_FILE` (required):
+    Path to file where the cloud config (openrc.sh) is located.
+    The configuration file is sourced by Machinery.
+
+  * `-i IMAGE_DIR`, `--image-dir=IMAGE_DIR` (optional):
+    Image file under specific path.
+
+  * `-n CLOUD_IMAGE_NAME`, `--cloud-image-name=CLOUD_IMAGE_NAME` (required):
+    Name of the image in the cloud.
+
+  * `-s`, `--insecure` (optional):
+    Allow to make "insecure" HTTPS requests, without checking the SSL
+    certificate when uploading to the cloud.
+
+## PREREQUISITES
+
+ * The `deploy` command requires the packages `kiwi` for building the image
+   and `python-glanceclient` for uploading the image to the cloud.
+
+## SUPPORTED ARCHITECTURES
+
+Machinery only supports deploying x86_64 images on x86_64 systems.
+
+## EXAMPLES
+
+ * Build an image under the system description named `jeos`.
+   Deploy it to the OpenStack cloud name `tux-cloud` by using the
+   configuration file `openrc.sh` in directory `tux`:
+
+    $ `machinery` deploy jeos -n tux-cloud -c tux/openrc.sh

data/manual/docs/machinery-export-autoyast.1.md

@@ -0,0 +1,58 @@
+
+# export-autoyast — Export System Description as AutoYasST profile
+
+## SYNOPSIS
+
+`machinery export-autoyast` -a | --autoyast-dir NAME
+   --force
+
+`machinery` help export-autoyast
+
+
+## DESCRIPTION
+
+The `export-autoyast` subcommand exports a stored system description as a AutoYaST
+profile.
+
+
+## ARGUMENTS
+
+  * `NAME` (required):
+    Name of the system description.
+
+
+## OPTIONS
+
+  * `-a AUTOYAST_DIR`, `--autoyast-dir=AUTOYAST_DIR` (required):
+    Write the AutoYaST profile to a subdirectory at the specified directory. The directory
+    will be created if it does not exist yet.
+
+  * `--force` (optional):
+    Overwrite existing system description
+
+
+## SYSTEM REGISTRATION
+
+  * To register a SLES 12 system automatically with AutoYaST, it is required to
+    edit the generated profile. The following example registers the system with
+    the SUSE Customer Center.
+
+```xml
+<suse_register>
+  <do_registration config:type="boolean">true</do_registration>
+  <email>tux@example.com</email>
+  <reg_code>MY_SECRET_REGCODE</reg_code>
+  <install_updates config:type="boolean">true</install_updates>
+  <slp_discovery config:type="boolean">false</slp_discovery>
+</suse_register>
+```
+
+  * More information can be found at the SUSE AutoYaST documentation.
+    https://www.suse.com/documentation/sles-12/singlehtml/book_autoyast/book_autoyast.html
+
+
+## EXAMPLES
+
+ * Export the `myhost` system description to `/tmp/myhost-autoyast`:
+
+    $ `machinery` export-autoyast myhost --autoyast-dir=/tmp

data/manual/docs/machinery-export-kiwi.1.md

@@ -0,0 +1,38 @@
+
+# export-kiwi — Export System Description as KIWI Image Description
+
+## SYNOPSIS
+
+`machinery export-kiwi` -k | --kiwi-dir NAME
+   --force
+
+`machinery` help export-kiwi
+
+
+## DESCRIPTION
+
+The `export-kiwi` subcommand exports a stored system description as a KIWI
+image description.
+
+
+## ARGUMENTS
+
+  * `NAME` (required):
+    Name of the system description.
+
+
+## OPTIONS
+
+  * `-k KIWI_DIR`, `--kiwi-dir=KIWI_DIR` (required):
+    Write the KIWI image description to a subdirectory at the specified directory. The directory
+    will be created if it does not exist yet.
+
+  * `--force` (optional):
+    Overwrite existing system description
+
+
+## EXAMPLES
+
+ * Export the `myhost` system description to `/tmp/myhost-kiwi`:
+
+    $ `machinery` export-kiwi myhost --kiwi-dir=/tmp

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

@@ -0,0 +1,108 @@
+
+# inspect-container — Inspect Container
+
+## SYNOPSIS
+
+`machinery inspect-container` [OPTIONS] IMAGENAME
+
+`machinery inspect-container` [OPTIONS] IMAGEID
+
+`machinery` help inspect-container
+
+
+## DESCRIPTION
+
+The `inspect-container` command inspects a container image. It creates and starts the container from the provided image before inspection
+and generates a system description from the gathered data. After the inspection the container will be killed and removed again.
+This approach ensures that no containers and images are affected by the inspection.
+
+Right now the container inspection only supports Docker images.
+
+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
+
+  * `IMAGENAME / IMAGEID` (required):
+    The name or id of the image to be inspected. The provided name or id 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 image for specified scope.
+    See the [Scope section](#Scopes) for more information.
+
+  * `-e SCOPE`, `--exclude-scope=EXCLUDE-SCOPE` (optional):
+    Inspect image for all scopes except the specified scope.
+    See the [Scope section](#Scopes) for more information.
+
+  * `-x`, `--extract-files` (optional):
+    Extract changed configuration and unmanaged files from the inspected container.
+    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 image.
+
+  * `--extract-unmanaged-files` (optional):
+    Extract unmanaged files from the inspected image.
+
+  * `--extract-changed-managed-files` (optional):
+    Extract changed managed files from inspected image.
+
+  * `--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-container --skip-files=@/path/to/filter_file myimage
+
+    If a filename contains a comma it needs to be escaped, e.g.
+
+      $ `machinery` inspect-container --skip-files=/file\\,with_comma myimage
+
+    **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 container requires an image specified by the name or id.
+
+  * The image to be inspected needs to have the following commands:
+
+    * `rpm` or `dpkg`
+    * `zypper`, `yum` or `apt-cache`
+    * `rsync`
+    * `cat`
+    * `sed`
+    * `find`
+
+## EXAMPLES
+
+  * Inspect Docker container `myimage` and save system description under name 'MyContainer':
+
+    $ `machinery` inspect-container --name=MyContainer myimage
+
+  * Inspect Docker container `076f46c1bef1` and save system description under name 'MySecondContainer':
+
+    $ `machinery` inspect-container --name=MySecondContainer 076f46c1bef1
+
+  * Extract changed managed files and save them:
+
+    $ `machinery` inspect-container --scope=changed-managed-files --extract-files myimage