machinery SUBCOMMAND [options]
machinery help [SUBCOMMAND]
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.
Machinery's core concept is the complete representation of a system by a universal system description. System descriptions are managed independently of the described systems which allows for system state conservation and offline preparation of 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. 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 between them or analyzed to deepen the knowledge about particular aspects of 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 flows and use cases. These are some implemented and planned use cases:
Migrate a physical system to a virtual environment:
Migrate a system while changing the configuration:
Using Machinery as an extension from other formats:
Machinery provides an extensible set of tools which can be combined to create higher-level work flows. It is designed for environments which focus on automation, integration of diverse tools and accountable management. Machinery integrates with existing configuration management solutions to address use cases currently not covered by them.
Machinery is implemented as a command line tool named machinery. The
machinery command has several subcommands for specific tasks. All
subcommands work with the same system description identified by an optional
name which can be used by all subcommands.
The system description is structured into "scopes". A scope covers a specific part of the configuration of the inspected system such as installed packages, repositories, or 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.
Machinery supports the following scopes:
os
Contains information about the operating system, name, version, and architecture of the inspected system.
packages
Contains information on all installed RPM packages installed on the inspected system.
config-files
Contains all configuration files which have been changed since they were installed. Configuration files are all those files which are marked as such in the package which has installed them. A configuration file is considered changed if either its content or its Linux permission bits have changed.
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
directories. Special files like device nodes, named pipes and Unix domain
sockets are ignored. The directories /tmp, /var/tmp, /sys, /dev,
/.snapshots/, and /var/run are ignored, too. If a directory is in this
list, no file or directory below it belongs to a RPM package.
Meta data information of unmanaged files is only available if the files were extracted during inspection.
Using the --extract-unmanaged-files option, the files are transferred from
the system and stored in the system description. Depending on the content of
the inspected system, the amount of data stored may be huge.
changed-managed-files
Contains the names and contents of all non-configuration files which have been changed compared to the files in the package.
patterns
Contains all patterns installed on the inspected system. A pattern is a
collection of software packages.
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.
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:
The alias name of the repository.
The repository type, rpm-md and YaST types that are used on SUSE systems.
The path to the repository. This could be a local path, a remote location, a device, or a file.
A boolean flag that indicates if this repository is in use or not.
A boolean flag that indicates if this repository should update the locally stored metadata files with metadata files from the origin automatically or not.
A boolean flag that indicates if packages which would be installed from this repository should be checked by their gpg key or not.
A numeric value for a priority. The priority of a repository is compared to the priorities of all other activated repositories. Values can range from 1 (highest) to 99 (lowest, default).
services
Services are applications running in the background doing continuous work
or waiting for requests to do work.
The scope determines which services are configured to be started in which
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 config files and are ignored in this context.
users
Contains information about the system users including user and group ids, login information, such as password hashes and - if available - additional password properties.
groups
Contains information about the system groups such as group attributes and the list of group members.
Some of the important use cases of Machinery are:
Inspecting a System and Collecting Information
Collecting a variety of information. Limit the gathered information with scopes (see section about scopes). Each inspection step updates the system description.
Reviewing System Description
After a successful inspection, the system description can be displayed on the console or the output can be fed into other tools.
Cloning a System
An inspected system can be cloned. The inspection step returns a system description which is used as the basis for cloning physical or virtual instances. Machinery can build a system image from the description, which can then for example be deployed to a cloud.
--versionDisplays version of machinery tool. Exit when done.
--debugEnable debug mode. Machinery writes additional information into the log file which can be useful to track down problems.
machinery analyze NAME -o | --operation=OPERATION
machinery help analyze
The analyze subcommand analyzes an existing system description and enriches
it with additional information. Supported operations are:
config-file-diffsmachinery show --show-diffsNAME (required)-o OPERATION, --operation=OPERATION (required)myhost system description:$ machinery analyze myhost --operation=config-file-diffs
machinery build NAME -i IMAGE-DIR | --image-dir=IMAGE-DIR
machinery help build
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 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.
NAME (required)-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
The build command requires the packages kiwi and kiwi-desc-vmbxoot.
All repositories in the system description must be accessible from the
build machine on which machinery build is called.
The following combinations of build hosts and targets are supported:
SUSE Linux Enterprise 12
Can build SUSE Linux Enterprise 12
openSUSE 13.1
Can build SUSE Linux Enterprise 11 and openSUSE 13.1
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/
machinery compare [-s SCOPE | --scope=SCOPE] [-e EXCLUDE-SCOPE | --exclude-scope=EXCLUDE-SCOPE] [--no-pager] [--show-all] NAME1 NAME2
machinery help compare
The compare command compares stored system descriptions. The scope option can
be used to limit the output to the given scopes.
NAME1 (required)First system description to compare.
NAME2 (required)Second system description to compare.
-s SCOPE, --scope=SCOPE (optional)Limit output to the specified scope. See the Scope section for more information.
-e SCOPE, --exclude-scope=EXCLUDE-SCOPE (optional)Skip output of the specified scope. See the Scope section 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).
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
machinery copy
FROM_NAME TO_NAME
machinery help copy
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.
FROM_NAME (required)Name of the source system description.
TO_NAME (required)Name of the target system description.
earth under the name moon:$ machinery copy earth moon
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]
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
-coption):read -s OS_PASSWORD_INPUT
and set the password in the
OS_PASSWORDvariable:export OS_PASSWORD=YOUR_PASSWORD
NAME (required)-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.
deploy command requires the packages kiwi for building the image
and python-glanceclient for uploading the image to the cloud.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
machinery export-kiwi -k | --kiwi-dir NAME
--force
machinery help export-kiwi
The export-kiwi subcommand exports a stored system description as a KIWI
image description.
NAME (required)-k KIWI_DIR, --kiwi-dir=KIWI_DIR (required)Write the KIWI image description to the specified directory. The directory will be created if it does not exist yet.
--force (optional)Overwrite existing system description
myhost system description to /tmp/export:$ machinery export-kiwi myhost --kiwi-dir=/tmp/export
machinery inspect OPTIONS HOSTNAME
machinery help inspect
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.
HOSTNAME (required)--name option.-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 for more information.
-e SCOPE, --exclude-scope=EXCLUDE-SCOPE (optional)Inspect system for all scopes except the specified scope. See the Scope section for more information.
-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.
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:
rpmzypperrsyncchkconfigcatsedfindtarInspect 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
machinery list
machinery help list
List all available system descriptions in the internal database. The list is sorted alphabetically and contains a name and the scopes for each system.
--verbose (optional)$ machinery list
$ machinery list --verbose
machinery remove [--all]
NAME
machinery help remove
The remove command removes a stored system description.
--all (optional)Remove all stored system descriptions.
--verbose (optional)Explain what is being done.
NAME (required)earth:$ machinery remove earth
$ machinery remove --all
machinery show [-s SCOPE | --scope=SCOPE] [-e EXCLUDE-SCOPE | --exclude-scope=EXCLUDE-SCOPE] [--no-pager] [--show-diffs] NAME
machinery help show
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.
NAME (required)-s SCOPE, --scope=SCOPE (optional)Limit output to the specified scope.
See the Scope section 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 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).
earth:$ machinery show earth
$ machinery show earth -s repositories
$ machinery show earth --scope=changed-managed-files
machinery validate NAME
machinery help validate
The validate subcommand validates an existing system description.
It checks, that the description has the correct structure and the data stored
there conforms to the required schema. It also verifies that all extracted files
are present on disk.
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.
NAME (required)myhost:$ machinery validate myhost
~/.machinery/machinery.log:Central log file, in the format date, time, process id, and log message.
eth0 (SLE11) and lan0 (SLE12):First network device is used when DHCP in built image is enabled.
MACHINERY_LOG_FILE:Location of Machinery's log file (defaults to ~/.machinery/machinery.log)
Copyright (c) 2013-2014 SUSE LLC