1. machinery(1)
  2. machinery(1)

Machinery — A Systems Management Toolkit for Linux

SYNOPSIS

machinery SUBCOMMAND [options]
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

Inspect Two Systems and Compare Them

Fully Inspect a System and Export a Kiwi Description

Fully Inspect a System and Export an AutoYaST Profile

Fully Inspect a System and Deploy a Replicate to the Cloud

How to upgrade a SLES 11 SP3 system to SLES 12

CONCEPTUAL OVERVIEW

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.

The machinery Command

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.

Scopes

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:

System Description

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.

Use Cases

Some of the important use cases of Machinery are:

OPTIONS FOR ALL SUBCOMMANDS

--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.

analyze — Analyze System Description

SYNOPSIS

machinery analyze NAME -o | --operation=OPERATION

machinery help analyze

DESCRIPTION

The analyze subcommand analyzes an existing system description and enriches it with additional information. Supported operations are:

config-file-diffs
Generates the diffs between the extracted changed config files from the system and the original versions from the RPM packages. The diffs can be shown using machinery show --show-diffs

ARGUMENTS

NAME (required)
Name of the system description.

OPTIONS

-o OPERATION, --operation=OPERATION (required)
The analyze operation to perform.

EXAMPLES

Analyze the config file diffs for the myhost system description:

$ machinery analyze myhost --operation=config-file-diffs

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 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

BUILD SUPPORT MATRIX

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.

EXAMPLES

compare — Compare System Descriptions

SYNOPSIS

machinery compare [-s SCOPE | --scope=SCOPE] [-e EXCLUDE-SCOPE | --exclude-scope=EXCLUDE-SCOPE] [--no-pager] [--show-all] 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 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).

EXAMPLES

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

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

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

SUPPORTED ARCHITECTURES

Machinery only supports deploying x86_64 images on x86_64 systems.

EXAMPLES

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

EXAMPLES

Export the myhost system description to /tmp/myhost-autoyast:

$ machinery export-autoyast myhost --autoyast-dir=/tmp

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

generate-html — Generate an HTML view of a System Description

SYNOPSIS

machinery generate-html NAME

machinery help generate-html

DESCRIPTION

The generate-html generates an HTML view of a system description. The index.html file can be found in the according system description directory, e.g. ~/.machinery/NAME/index.html.

ARGUMENTS

NAME (required)
Name of the system description.

EXAMPLES

Create an HTML view of the moon system description:

$ machinery generate-html moon

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 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.

PREREQUISITES

EXAMPLES

list — List System Descriptions

SYNOPSIS

machinery list

machinery help list

DESCRIPTION

List all available system descriptions in the internal database. 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.

EXAMPLES

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

remove — Remove System Descriptions

SYNOPSIS

machinery remove [--all] NAME

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

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 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)

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

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

validate — Validate System Description

SYNOPSIS

machinery validate NAME

machinery help validate

DESCRIPTION

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.

ARGUMENTS

NAME (required)
Name of the system description.

EXAMPLES

Validate the system description with the name myhost:

$ machinery validate myhost

FILES AND DEVICES

~/.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.

ENVIRONMENT

MACHINERY_LOG_FILE:

Location of Machinery's log file (defaults to ~/.machinery/machinery.log)

Copyright (c) 2013-2015 SUSE LLC

  1. June 2015
  2. machinery(1)