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 inspect --extract-files --name=NAME HOSTNAMEmachinery show NAMEmachinery inspect HOSTNAME1machinery inspect HOSTNAME2machinery compare HOSTNAME1 HOSTNAME2machinery inspect --extract-files HOSTNAMEmachinery export-kiwi --kiwi-dir=~/kiwi HOSTNAMEmachinery inspect --extract-files HOSTNAMEmachinery export-autoyast --autoyast-dir=~/autoyast HOSTNAMEmachinery inspect --extract-files HOSTNAMEmachinery deploy --cloud-config=~/openrc.sh HOSTNAMEMachinery'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.
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).
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.
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.
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 change is reported if its content or its attributes like Linux permission bits or ownership have changed.
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
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, /.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.
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.
The System Description format and file structure is documented in the machinery wiki: 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.
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.
Machinery only supports building x86_64 images on x86_64 systems.
To see the list of supported combinations of build hosts and targets run
machinery build --help.
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 config
machinery config KEY
machinery config KEY=VALUE
machinery help config
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.
KEYName of the configuration entry.
VALUEValue of the configuration entry.
$ machinery config hints=off
$ machinery config hints
$ machinery config
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.Machinery only supports deploying x86_64 images on x86_64 systems.
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-autoyast -a | --autoyast-dir NAME
--force
machinery help export-autoyast
The export-autoyast subcommand exports a stored system description as a AutoYaST
profile.
NAME (required)-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
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.
<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>
myhost system description to /tmp/myhost-autoyast:$ machinery export-autoyast myhost --autoyast-dir=/tmp
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 a subdirectory at 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/myhost-kiwi:$ machinery export-kiwi myhost --kiwi-dir=/tmp
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.
-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
-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.
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:
rpmzypper or yumrsyncchkconfigcatsedfindtarWhen inspecting as non-root the user has to have the following command whitelist given in the sudoers file:
machinery ALL=(ALL) NOPASSWD: /usr/bin/find,/usr/bin/cat,/bin/cat,/usr/bin/rsync,/bin/rpm -V *,/bin/tar --create *
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 machineryInspect 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
machinery list
[NAME[,NAME2[,NAME3]]]
machinery help list
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.
--verbose (optional)--short (optional)a and b:$ machinery list a b
$ machinery list
$ machinery list --verbose
$ machinery list --short
machinery man
The man command shows the Machinery man page.
machinery move
FROM_NAME TO_NAME
machinery help move
The move command renames a stored system description from FROM_NAME to TO_NAME.
FROM_NAME (required)Current name of the system description.
TO_NAME (required)New name of the system description.
earth to moon:$ machinery move earth moon
machinery remove [--all]
[NAME[,NAME2[,NAME3]]]
machinery help remove
The remove command removes all specified system descriptions.
--all (optional)Remove all stored system descriptions.
--verbose (optional)Explain what is being done.
NAME... (required)earth:$ machinery remove earth
earth and moon:$ machinery remove earth moon
$ machinery remove --all
machinery serve [-p PORT | --port=PORT] [-i IP | --ip=IP] NAME
machinery help serve
The serve command spawns a web server and serves a stored system description on
it.
By default the description is available from http://127.0.0.1:7585 but both the
IP address and the port can be configured using the according options.
NAME (required)-p PORT, --port=PORT (optional)Specify the port on which the web server will serve the system description: 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.
-i IP, --ip=IP (optional)Specify the IP address on which the web server will be made available. Default: 127.0.0.1
It's only possible to use an IP address (or hostnames resolving to an IP address) which is assigned to a network interface on the local machine.
earth:$ machinery serve earth
$ machinery serve earth -i 10.10.100.123 -p 3000
machinery show [-s SCOPE | --scope=SCOPE] [-e EXCLUDE-SCOPE | --exclude-scope=EXCLUDE-SCOPE] [--no-pager] [--show-diffs] [--html] [-p PORT | --port=PORT] [-i IP | --ip=IP] 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).
--html (optional)Run a web server and open the system description in HTML format in your web browser using the
xdg-open command.
-p PORT, --port=PORT (optional)Specify the port on which the web server will serve the system description: 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.
-i IP, --ip=IP (optional)Specify the IP address on which the web server will be made available. Default: 127.0.0.1
It's only possible to use an IP address (or hostnames resolving to an IP address) which is assigned to a network interface on the local machine.
--verbose (optional)Display the filters which were applied before showing the system description.
earth:$ machinery show earth
$ machinery show earth -s repositories
$ machinery show earth --scope=changed-managed-files
machinery upgrade-format --all
machinery upgrade-format NAME
machinery help upgrade-format
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.
--all (optional)NAME (optional)earth:$ machinery upgrade-format earth
$ machinery upgrade-format --all
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 and that all files have meta information.
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.config:Configuration file.
~/.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-2015 SUSE LLC