{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"docs/","text":"Machinery Documentation Welcome! The Machinary documentation is a reference aimed at system administrators. It will give you an overview of Machinery itself, its subcommands, and usage examples. What is Machinery? Machinery is a systems management toolkit for Linux. It supports configuration discovery, system validation, and service migration. Machinery is based on the idea of a 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 machinery inspect --extract-files --name=NAME HOSTNAME machinery show NAME Export System Description as HTML machinery export-html --html-dir=tmp NAME Inspect Two Systems and Compare Them machinery inspect HOSTNAME1 machinery inspect HOSTNAME2 machinery compare HOSTNAME1 HOSTNAME2 Fully Inspect a System and Export a Kiwi Description machinery inspect --extract-files HOSTNAME machinery export-kiwi --kiwi-dir=~/kiwi HOSTNAME Fully Inspect a System and Export an AutoYaST Profile machinery inspect --extract-files HOSTNAME machinery export-autoyast --autoyast-dir=~/autoyast HOSTNAME Fully Inspect a System and Deploy a Replicate to the Cloud machinery inspect --extract-files HOSTNAME machinery deploy --cloud-config=~/openrc.sh HOSTNAME How to upgrade a SLES 11 SP3 system to SLES 12 Machinery can help you to upgrade without affecting the original system. For more details please read the Wiki Page: How to upgrade a SLES 11 SP3 system to SLES 12 . For a more detailed overview see General Overview .","title":"Welcome"},{"location":"docs/#machinery-documentation","text":"Welcome! The Machinary documentation is a reference aimed at system administrators. It will give you an overview of Machinery itself, its subcommands, and usage examples.","title":"Machinery Documentation"},{"location":"docs/#what-is-machinery","text":"Machinery is a systems management toolkit for Linux. It supports configuration discovery, system validation, and service migration. Machinery is based on the idea of a 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.","title":"What is Machinery?"},{"location":"docs/#work-flow-examples","text":"","title":"Work Flow Examples"},{"location":"docs/#inspect-a-system-and-show-results","text":"machinery inspect --extract-files --name=NAME HOSTNAME machinery show NAME","title":"Inspect a System and Show Results"},{"location":"docs/#export-system-description-as-html","text":"machinery export-html --html-dir=tmp NAME","title":"Export System Description as HTML"},{"location":"docs/#inspect-two-systems-and-compare-them","text":"machinery inspect HOSTNAME1 machinery inspect HOSTNAME2 machinery compare HOSTNAME1 HOSTNAME2","title":"Inspect Two Systems and Compare Them"},{"location":"docs/#fully-inspect-a-system-and-export-a-kiwi-description","text":"machinery inspect --extract-files HOSTNAME machinery export-kiwi --kiwi-dir=~/kiwi HOSTNAME","title":"Fully Inspect a System and Export a Kiwi Description"},{"location":"docs/#fully-inspect-a-system-and-export-an-autoyast-profile","text":"machinery inspect --extract-files HOSTNAME machinery export-autoyast --autoyast-dir=~/autoyast HOSTNAME","title":"Fully Inspect a System and Export an AutoYaST Profile"},{"location":"docs/#fully-inspect-a-system-and-deploy-a-replicate-to-the-cloud","text":"machinery inspect --extract-files HOSTNAME machinery deploy --cloud-config=~/openrc.sh HOSTNAME","title":"Fully Inspect a System and Deploy a Replicate to the Cloud"},{"location":"docs/#how-to-upgrade-a-sles-11-sp3-system-to-sles-12","text":"Machinery can help you to upgrade without affecting the original system. For more details please read the Wiki Page: How to upgrade a SLES 11 SP3 system to SLES 12 . For a more detailed overview see General Overview .","title":"How to upgrade a SLES 11 SP3 system to SLES 12"},{"location":"docs/machinery-analyze.1/","text":"analyze \u2014 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: changed-config-files-diffs : Generates the diffs between the extracted changed configuration files from the system and the original versions from the 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=changed-config-files-diffs","title":"Analyze"},{"location":"docs/machinery-analyze.1/#analyze-analyze-system-description","text":"","title":"analyze \u2014 Analyze System Description"},{"location":"docs/machinery-analyze.1/#synopsis","text":"machinery analyze NAME -o | --operation=OPERATION machinery help analyze","title":"Synopsis"},{"location":"docs/machinery-analyze.1/#description","text":"The analyze subcommand analyzes an existing system description and enriches it with additional information. Supported operations are: changed-config-files-diffs : Generates the diffs between the extracted changed configuration files from the system and the original versions from the packages. The diffs can be shown using machinery show --show-diffs","title":"Description"},{"location":"docs/machinery-analyze.1/#arguments","text":"NAME (required): Name of the system description.","title":"Arguments"},{"location":"docs/machinery-analyze.1/#options","text":"-o OPERATION , --operation=OPERATION (required): The analyze operation to perform.","title":"Options"},{"location":"docs/machinery-analyze.1/#examples","text":"Analyze the config file diffs for the myhost system description: $ machinery analyze myhost --operation=changed-config-files-diffs","title":"Examples"},{"location":"docs/machinery-build.1/","text":"build \u2014 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 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/","title":"Build"},{"location":"docs/machinery-build.1/#build-build-image-from-system-description","text":"","title":"build \u2014 Build Image from System Description"},{"location":"docs/machinery-build.1/#synopsis","text":"machinery build NAME -i IMAGE-DIR | --image-dir=IMAGE-DIR machinery help build","title":"Synopsis"},{"location":"docs/machinery-build.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-build.1/#arguments","text":"NAME (required): Use specified system description.","title":"Arguments"},{"location":"docs/machinery-build.1/#options","text":"-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","title":"Options"},{"location":"docs/machinery-build.1/#prerequisites","text":"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.","title":"Prerequisites"},{"location":"docs/machinery-build.1/#examples","text":"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/","title":"Examples"},{"location":"docs/machinery-compare.1/","text":"compare \u2014 Compare System Descriptions Synopsis machinery compare [-s SCOPE | --scope=SCOPE] [-e IGNORE-SCOPE | --ignore-scope=IGNORE-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 for more information. -e SCOPE , --ignore-scope=IGNORE-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). --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","title":"Compare"},{"location":"docs/machinery-compare.1/#compare-compare-system-descriptions","text":"","title":"compare \u2014 Compare System Descriptions"},{"location":"docs/machinery-compare.1/#synopsis","text":"machinery compare [-s SCOPE | --scope=SCOPE] [-e IGNORE-SCOPE | --ignore-scope=IGNORE-SCOPE] [--no-pager] [--show-all] [--html] NAME1 NAME2 machinery help compare","title":"Synopsis"},{"location":"docs/machinery-compare.1/#description","text":"The compare command compares stored system descriptions. The scope option can be used to limit the output to the given scopes.","title":"Description"},{"location":"docs/machinery-compare.1/#arguments","text":"NAME1 (required): First system description to compare. NAME2 (required): Second system description to compare.","title":"Arguments"},{"location":"docs/machinery-compare.1/#options","text":"-s SCOPE , --scope=SCOPE (optional): Limit output to the specified scope. See the Scope section for more information. -e SCOPE , --ignore-scope=IGNORE-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). --html (optional): Shows the comparison of two system descriptions in the web browser.","title":"Options"},{"location":"docs/machinery-compare.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-config.1/","text":"config \u2014 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","title":"Config"},{"location":"docs/machinery-config.1/#config-configure-machinery","text":"","title":"config \u2014 Configure Machinery"},{"location":"docs/machinery-config.1/#synopsis","text":"machinery config machinery config KEY machinery config KEY=VALUE machinery help config","title":"Synopsis"},{"location":"docs/machinery-config.1/#description","text":"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 .","title":"Description"},{"location":"docs/machinery-config.1/#arguments","text":"KEY : Name of the configuration entry. VALUE : Value of the configuration entry.","title":"Arguments"},{"location":"docs/machinery-config.1/#examples","text":"Turn off hints: $ machinery config hints=off Show current configuration of hints: $ machinery config hints List all configuration entries and their values: $ machinery config","title":"Examples"},{"location":"docs/machinery-copy.1/","text":"copy \u2014 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","title":"Copy"},{"location":"docs/machinery-copy.1/#copy-copy-system-description","text":"","title":"copy \u2014 Copy System Description"},{"location":"docs/machinery-copy.1/#synopsis","text":"machinery copy FROM_NAME TO_NAME machinery help copy","title":"Synopsis"},{"location":"docs/machinery-copy.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-copy.1/#arguments","text":"FROM_NAME (required): Name of the source system description. TO_NAME (required): Name of the target system description.","title":"Arguments"},{"location":"docs/machinery-copy.1/#examples","text":"Create a copy of the system description earth under the name moon : $ machinery copy earth moon","title":"Examples"},{"location":"docs/machinery-deploy.1/","text":"deploy \u2014 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 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","title":"Deploy"},{"location":"docs/machinery-deploy.1/#deploy-deploy-image-to-openstack-cloud","text":"","title":"deploy \u2014 Deploy Image to OpenStack Cloud"},{"location":"docs/machinery-deploy.1/#synopsis","text":"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]","title":"Synopsis"},{"location":"docs/machinery-deploy.1/#description","text":"The deploy command builds and deploys an image to an OpenStack cloud. This command is particularly useful for testing, debugging, or validation.","title":"Description"},{"location":"docs/machinery-deploy.1/#note-set-password-for-unattended-work","text":"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","title":"NOTE: Set Password for Unattended Work"},{"location":"docs/machinery-deploy.1/#arguments","text":"NAME (required): Name of the system description.","title":"Arguments"},{"location":"docs/machinery-deploy.1/#options","text":"-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.","title":"Options"},{"location":"docs/machinery-deploy.1/#prerequisites","text":"The deploy command requires the packages kiwi for building the image and python-glanceclient for uploading the image to the cloud.","title":"Prerequisites"},{"location":"docs/machinery-deploy.1/#supported-architectures","text":"Machinery only supports deploying x86_64 images on x86_64 systems.","title":"Supported Architectures"},{"location":"docs/machinery-deploy.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-export-autoyast.1/","text":"export-autoyast \u2014 Export System Description as AutoYasST profile Synopsis machinery export-autoyast -a | --autoyast-dir=DIRECTORY NAME --force machinery help export-autoyast Description The export-autoyast subcommand exports a stored system description as an 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 an existing output directory. 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. <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 . Examples Export the myhost system description to /tmp/myhost-autoyast : $ machinery export-autoyast myhost --autoyast-dir=/tmp","title":"Export AutoYaST"},{"location":"docs/machinery-export-autoyast.1/#export-autoyast-export-system-description-as-autoyasst-profile","text":"","title":"export-autoyast \u2014 Export System Description as AutoYasST profile"},{"location":"docs/machinery-export-autoyast.1/#synopsis","text":"machinery export-autoyast -a | --autoyast-dir=DIRECTORY NAME --force machinery help export-autoyast","title":"Synopsis"},{"location":"docs/machinery-export-autoyast.1/#description","text":"The export-autoyast subcommand exports a stored system description as an AutoYaST profile.","title":"Description"},{"location":"docs/machinery-export-autoyast.1/#arguments","text":"NAME (required): Name of the system description.","title":"Arguments"},{"location":"docs/machinery-export-autoyast.1/#options","text":"-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 an existing output directory.","title":"Options"},{"location":"docs/machinery-export-autoyast.1/#system-registration","text":"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> More information can be found at the SUSE AutoYaST documentation .","title":"System Registration"},{"location":"docs/machinery-export-autoyast.1/#examples","text":"Export the myhost system description to /tmp/myhost-autoyast : $ machinery export-autoyast myhost --autoyast-dir=/tmp","title":"Examples"},{"location":"docs/machinery-export-html.1/","text":"export-html \u2014 Export System Description as HTML Synopsis machinery export-html -d | --html-dir=DIRECTORY NAME --force machinery help export-html Description The export-html subcommand exports a stored system description as HTML. Arguments NAME (required): Name of the system description. Options -d DIRECTORY , --html-dir=DIRECTORY (required): Write the HTML page and assets to this directory. The directory will be created if it does not exist yet. --force (optional): Delete the directory if it exists and recreate it. Examples Export the myhost system description to /tmp/myhost-html : $ machinery export-html --html-dir=/tmp myhost","title":"Export HTML"},{"location":"docs/machinery-export-html.1/#export-html-export-system-description-as-html","text":"","title":"export-html \u2014 Export System Description as HTML"},{"location":"docs/machinery-export-html.1/#synopsis","text":"machinery export-html -d | --html-dir=DIRECTORY NAME --force machinery help export-html","title":"Synopsis"},{"location":"docs/machinery-export-html.1/#description","text":"The export-html subcommand exports a stored system description as HTML.","title":"Description"},{"location":"docs/machinery-export-html.1/#arguments","text":"NAME (required): Name of the system description.","title":"Arguments"},{"location":"docs/machinery-export-html.1/#options","text":"-d DIRECTORY , --html-dir=DIRECTORY (required): Write the HTML page and assets to this directory. The directory will be created if it does not exist yet. --force (optional): Delete the directory if it exists and recreate it.","title":"Options"},{"location":"docs/machinery-export-html.1/#examples","text":"Export the myhost system description to /tmp/myhost-html : $ machinery export-html --html-dir=/tmp myhost","title":"Examples"},{"location":"docs/machinery-export-kiwi.1/","text":"export-kiwi \u2014 Export System Description as KIWI Image Description Synopsis machinery export-kiwi -k | --kiwi-dir=DIRECTORY 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 an existing output directory. Examples Export the myhost system description to /tmp/myhost-kiwi : $ machinery export-kiwi myhost --kiwi-dir=/tmp","title":"Export Kiwi"},{"location":"docs/machinery-export-kiwi.1/#export-kiwi-export-system-description-as-kiwi-image-description","text":"","title":"export-kiwi \u2014 Export System Description as KIWI Image Description"},{"location":"docs/machinery-export-kiwi.1/#synopsis","text":"machinery export-kiwi -k | --kiwi-dir=DIRECTORY NAME --force machinery help export-kiwi","title":"Synopsis"},{"location":"docs/machinery-export-kiwi.1/#description","text":"The export-kiwi subcommand exports a stored system description as a KIWI image description.","title":"Description"},{"location":"docs/machinery-export-kiwi.1/#arguments","text":"NAME (required): Name of the system description.","title":"Arguments"},{"location":"docs/machinery-export-kiwi.1/#options","text":"-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 an existing output directory.","title":"Options"},{"location":"docs/machinery-export-kiwi.1/#examples","text":"Export the myhost system description to /tmp/myhost-kiwi : $ machinery export-kiwi myhost --kiwi-dir=/tmp","title":"Examples"},{"location":"docs/machinery-inspect-container.1/","text":"inspect-container \u2014 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 for more information. -e SCOPE , --ignore-scope=IGNORE-SCOPE (optional): Inspect image 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 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","title":"Inspect Container"},{"location":"docs/machinery-inspect-container.1/#inspect-container-inspect-container","text":"","title":"inspect-container \u2014 Inspect Container"},{"location":"docs/machinery-inspect-container.1/#synopsis","text":"machinery inspect-container [OPTIONS] IMAGENAME machinery inspect-container [OPTIONS] IMAGEID machinery help inspect-container","title":"Synopsis"},{"location":"docs/machinery-inspect-container.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-inspect-container.1/#arguments","text":"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.","title":"Arguments"},{"location":"docs/machinery-inspect-container.1/#options","text":"-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 for more information. -e SCOPE , --ignore-scope=IGNORE-SCOPE (optional): Inspect image 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 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.","title":"Options"},{"location":"docs/machinery-inspect-container.1/#prerequisites","text":"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","title":"Prerequisites"},{"location":"docs/machinery-inspect-container.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-inspect.1/","text":"inspect \u2014 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. Note : Tasks on Debian-like systems are treated as patterns. 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 , --ignore-scope=IGNORE-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 -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","title":"Inspect"},{"location":"docs/machinery-inspect.1/#inspect-inspect-running-system","text":"","title":"inspect \u2014 Inspect Running System"},{"location":"docs/machinery-inspect.1/#synopsis","text":"machinery inspect [OPTIONS] HOSTNAME machinery help inspect","title":"Synopsis"},{"location":"docs/machinery-inspect.1/#description","text":"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. Note : Tasks on Debian-like systems are treated as patterns.","title":"Description"},{"location":"docs/machinery-inspect.1/#arguments","text":"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.","title":"Arguments"},{"location":"docs/machinery-inspect.1/#options","text":"-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 , --ignore-scope=IGNORE-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 -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.","title":"Options"},{"location":"docs/machinery-inspect.1/#prerequisites","text":"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","title":"Prerequisites"},{"location":"docs/machinery-inspect.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-list.1/","text":"list \u2014 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","title":"List"},{"location":"docs/machinery-list.1/#list-list-system-descriptions","text":"","title":"list \u2014 List System Descriptions"},{"location":"docs/machinery-list.1/#synopsis","text":"machinery list [OPTIONS] [NAME[,NAME2[,NAME3]]] machinery help list","title":"Synopsis"},{"location":"docs/machinery-list.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-list.1/#options","text":"--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.","title":"Options"},{"location":"docs/machinery-list.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-man.1/","text":"man \u2014 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. Description The man command shows the Machinery man page.","title":"Man"},{"location":"docs/machinery-man.1/#man-shows-man-page","text":"","title":"man \u2014 Shows Man Page"},{"location":"docs/machinery-man.1/#synopsis","text":"machinery man [OPTIONS]","title":"Synopsis"},{"location":"docs/machinery-man.1/#options","text":"--html (optional): Run a web server and open the documentation in HTML format in your web browser.","title":"Options"},{"location":"docs/machinery-man.1/#description","text":"The man command shows the Machinery man page.","title":"Description"},{"location":"docs/machinery-move.1/","text":"move \u2014 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","title":"Move"},{"location":"docs/machinery-move.1/#move-move-system-description","text":"","title":"move \u2014 Move System Description"},{"location":"docs/machinery-move.1/#synopsis","text":"machinery move FROM_NAME TO_NAME machinery help move","title":"Synopsis"},{"location":"docs/machinery-move.1/#description","text":"The move command renames a stored system description from FROM_NAME to TO_NAME .","title":"Description"},{"location":"docs/machinery-move.1/#arguments","text":"FROM_NAME (required): Current name of the system description. TO_NAME (required): New name of the system description.","title":"Arguments"},{"location":"docs/machinery-move.1/#examples","text":"Rename the system description earth to moon : $ machinery move earth moon","title":"Examples"},{"location":"docs/machinery-remove.1/","text":"remove \u2014 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","title":"Remove"},{"location":"docs/machinery-remove.1/#remove-remove-system-descriptions","text":"","title":"remove \u2014 Remove System Descriptions"},{"location":"docs/machinery-remove.1/#synopsis","text":"machinery remove [--all] [NAME[,NAME2[,NAME3]]] machinery help remove","title":"Synopsis"},{"location":"docs/machinery-remove.1/#description","text":"The remove command removes all specified system descriptions.","title":"Description"},{"location":"docs/machinery-remove.1/#options","text":"--all (optional): Remove all stored system descriptions. --verbose (optional): Explain what is being done.","title":"Options"},{"location":"docs/machinery-remove.1/#arguments","text":"NAME... (required): Remove specified system descriptions.","title":"Arguments"},{"location":"docs/machinery-remove.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-serve.1/","text":"serve \u2014 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","title":"Serve"},{"location":"docs/machinery-serve.1/#serve-serve-system-descriptions-using-a-web-server","text":"","title":"serve \u2014 Serve System Descriptions Using a Web Server"},{"location":"docs/machinery-serve.1/#synopsis","text":"machinery serve [-p PORT | --port=PORT] [--public] machinery help serve","title":"Synopsis"},{"location":"docs/machinery-serve.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-serve.1/#options","text":"-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","title":"Options"},{"location":"docs/machinery-serve.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-show.1/","text":"show \u2014 Show System Description Synopsis machinery show [-s SCOPE | --scope=SCOPE] [-e IGNORE-SCOPE | --ignore-scope=IGNORE-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 IGNORE-SCOPE , --ignore-scope=IGNORE-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. --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","title":"Show"},{"location":"docs/machinery-show.1/#show-show-system-description","text":"","title":"show \u2014 Show System Description"},{"location":"docs/machinery-show.1/#synopsis","text":"machinery show [-s SCOPE | --scope=SCOPE] [-e IGNORE-SCOPE | --ignore-scope=IGNORE-SCOPE] [--no-pager] [--show-diffs] [--html] NAME machinery help show","title":"Synopsis"},{"location":"docs/machinery-show.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-show.1/#arguments","text":"NAME (required): Use specified system description.","title":"Arguments"},{"location":"docs/machinery-show.1/#options","text":"-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 IGNORE-SCOPE , --ignore-scope=IGNORE-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. --verbose (optional): Display the filters which were applied before showing the system description.","title":"Options"},{"location":"docs/machinery-show.1/#examples","text":"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","title":"Examples"},{"location":"docs/machinery-upgrade-format.1/","text":"upgrade-format \u2014 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","title":"Upgrade Format"},{"location":"docs/machinery-upgrade-format.1/#upgrade-format-upgrade-system-description","text":"","title":"upgrade-format \u2014 Upgrade System Description"},{"location":"docs/machinery-upgrade-format.1/#synopsis","text":"machinery upgrade-format --all machinery upgrade-format NAME machinery help upgrade-format","title":"Synopsis"},{"location":"docs/machinery-upgrade-format.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-upgrade-format.1/#options","text":"--all (optional): Upgrade all stored system descriptions.","title":"Options"},{"location":"docs/machinery-upgrade-format.1/#arguments","text":"NAME (optional): Upgrade specified system description.","title":"Arguments"},{"location":"docs/machinery-upgrade-format.1/#examples","text":"Upgrade the system description stored as earth : $ machinery upgrade-format earth Upgrade all stored system descriptions: $ machinery upgrade-format --all","title":"Examples"},{"location":"docs/machinery-validate.1/","text":"validate \u2014 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","title":"Validate"},{"location":"docs/machinery-validate.1/#validate-validate-system-description","text":"","title":"validate \u2014 Validate System Description"},{"location":"docs/machinery-validate.1/#synopsis","text":"machinery validate NAME machinery help validate","title":"Synopsis"},{"location":"docs/machinery-validate.1/#description","text":"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.","title":"Description"},{"location":"docs/machinery-validate.1/#arguments","text":"NAME (required): Name of the system description.","title":"Arguments"},{"location":"docs/machinery-validate.1/#examples","text":"Validate the system description with the name myhost : $ machinery validate myhost","title":"Examples"},{"location":"docs/machinery_main_general.1/","text":"Machinery \u2014 A Systems Management Toolkit for Linux Synopsis machinery SUBCOMMAND [options] machinery help [SUBCOMMAND] 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 existing 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 accommodate higher-level work flows and use cases. These are some implemented and planned use cases: Migrate a physical system to a virtual environment: Inspect a system to obtain a system description Export the system description to a Kiwi configuration Build a cloud image from the configuration Deploy the image to the cloud Migrate a system while changing the configuration: Inspect a system to obtain a system description Modify the system description Build image for deployment Using Machinery as an extension from other formats: Import AutoYaST profile as system description Build image for deployment 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. System Description The System Description format and file structure is documented in the 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. 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 changed 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. See the Scopes documentation for a list of all supported scopes. 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. Files and Devices ~/.machinery/machinery.config : Configuration file. ~/.machinery/machinery.log : Central log file, in the format date, time, process id, and log message. em1 (openSUSE 13.2 / openSUSE leap) , 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 Copyright (c) 2013-2016 SUSE LLC","title":"General Overview"},{"location":"docs/machinery_main_general.1/#machinery-a-systems-management-toolkit-for-linux","text":"","title":"Machinery \u2014 A Systems Management Toolkit for Linux"},{"location":"docs/machinery_main_general.1/#synopsis","text":"machinery SUBCOMMAND [options] machinery help [SUBCOMMAND]","title":"Synopsis"},{"location":"docs/machinery_main_general.1/#conceptual-overview","text":"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 existing 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 accommodate higher-level work flows and use cases. These are some implemented and planned use cases: Migrate a physical system to a virtual environment: Inspect a system to obtain a system description Export the system description to a Kiwi configuration Build a cloud image from the configuration Deploy the image to the cloud Migrate a system while changing the configuration: Inspect a system to obtain a system description Modify the system description Build image for deployment Using Machinery as an extension from other formats: Import AutoYaST profile as system description Build image for deployment 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.","title":"Conceptual Overview"},{"location":"docs/machinery_main_general.1/#the-machinery-command","text":"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.","title":"The machinery Command"},{"location":"docs/machinery_main_general.1/#system-description","text":"The System Description format and file structure is documented in the 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.","title":"System Description"},{"location":"docs/machinery_main_general.1/#scopes","text":"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 changed 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. See the Scopes documentation for a list of all supported scopes.","title":"Scopes"},{"location":"docs/machinery_main_general.1/#options-for-all-subcommands","text":"--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.","title":"Options for All Subcommands"},{"location":"docs/machinery_main_general.1/#files-and-devices","text":"~/.machinery/machinery.config : Configuration file. ~/.machinery/machinery.log : Central log file, in the format date, time, process id, and log message. em1 (openSUSE 13.2 / openSUSE leap) , eth0 (SLE11) and lan0 (SLE12): First network device is used when DHCP in built image is enabled.","title":"Files and Devices"},{"location":"docs/machinery_main_general.1/#environment","text":"MACHINERY_LOG_FILE : Location of Machinery's log file (defaults to ~/.machinery/machinery.log ).","title":"Environment"},{"location":"docs/machinery_main_general.1/#copyright","text":"Copyright (c) 2013-2016 SUSE LLC","title":"Copyright"},{"location":"docs/machinery_main_scopes.1/","text":"Scopes os Contains information about the operating system, name, version, and architecture of the inspected system. packages Contains information on all installed packages installed on the inspected system. patterns Contains all patterns or tasks installed on the inspected system. A pattern is a collection of software packages, similar to the idea of tasks on Debian/Ubuntu- like systems. The meaning of software patterns depends on the package manager of the distribution. repositories Contains all information about software repositories configured on the inspected system. The information about repositories depends on the package manager of the distribution. 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 configuration files and are ignored in this context. changed-config-files Contains all configuration files which have been changed since they were installed. Changed 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 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 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.","title":"Scopes"},{"location":"docs/machinery_main_scopes.1/#scopes","text":"os Contains information about the operating system, name, version, and architecture of the inspected system. packages Contains information on all installed packages installed on the inspected system. patterns Contains all patterns or tasks installed on the inspected system. A pattern is a collection of software packages, similar to the idea of tasks on Debian/Ubuntu- like systems. The meaning of software patterns depends on the package manager of the distribution. repositories Contains all information about software repositories configured on the inspected system. The information about repositories depends on the package manager of the distribution. 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 configuration files and are ignored in this context. changed-config-files Contains all configuration files which have been changed since they were installed. Changed 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 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 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.","title":"Scopes"},{"location":"docs/machinery_main_security_implications.1/","text":"Security Implications This document describes security related issues administrators need to be aware of when using Machinery. Inspection Machinery inspects several parts of a system which are covered by Machinery's scopes. Information about scopes is listed here . Users of Machinery who inspect systems need to be aware of the security implications to take the right decisions on how to protect the retrieved data. Retrieval of Data Machinery transfers data from one end point to another via SSH (Secure Shell, using public key authentication). Depending on the scope, Machinery collects information about files on the system. Additionally, when the --extract-files option is given for the inspect command, not only the meta data about the files (e.g. permission bits, owner, group etc .) but also the file content is extracted. Machinery does not distinguish between sensitive data (such as private keys or password files). That means that everyone with access to the system description has automatically access to all extracted files and contained sensitive data. root/sudo Privileges An inspection can only be done, when the user on the inspected system is either root or has sudo privileges. Information about the required sudo configuration can be found here . Storage of Data Access Restrictions After an inspection has been completed, the directory where the description is stored is made readable only for the user. The data is not encrypted by Machinery. Used Permission Bits When Machinery extracts data, it sets permission bits for files and directories as follows: Permission Bits Used for ... 0700 ... directories inside the description directory 0600 ... for files inside the description directory Accessing System Descriptions By default, all system descriptions are stored in the directory .machinery in the home directory of the user running Machinery. The directory can be redefined by the environment variable $MACHINERY_DIR . Each description has its own subdirectory. There is a manifest.json file in each description directory which contains the data of the inspection. Extracted files are stored in separate subdirectories inside the same description directory. Presentation of Data There are several ways how data can be presented to one or more users. The user has the option to either start a web server and view descriptions or view the descriptions only in the console. The following commands are used to present data to users: show compare serve list All of the commands listed above also have a --html option. When this option is used, Machinery starts a web server what will listen on the IP address 127.0.0.1 . The serve command offers also a --public option which makes the server listen on all configured IP addresses. WARNING: When making the server reachable from the outside, users can modify the link to access also other descriptions. There is currently no way to restrict the access to only one description. The serve command also allows the user to specify a port via the --port option. When no port is specified, the default port which is configured in the machinery config file in ~/.machinery/machinery.config ) will be taken. Export of Data export-autoyast The export-autoyast command creates an AutoYaST profile for an automated installation. This will result in tar balls containing the extracted files from the system description. These files potentially contain sensitive data (e.g. passwords). This fact needs to be kept in mind, especially if these files are copied to a web server for an AutoYaST installation via HTTP. export-kiwi The program kiwi allows you to build OS images for deployment. Machinery gives you the opportunity to export a KIWI description. This description can be used to build an image via Kiwi. The export-kiwi command creates a directory, where it stores the Kiwi configuration and the files of a system description. These files potentially contain sensitive data (e.g. passwords). build The created image potentially contains sensitive data (e.g. passwords) from extracted files. deploy The uploaded image potentially contains sensitive data (e.g. passwords) from extracted files.","title":"Security Implications"},{"location":"docs/machinery_main_security_implications.1/#security-implications","text":"This document describes security related issues administrators need to be aware of when using Machinery.","title":"Security Implications"},{"location":"docs/machinery_main_security_implications.1/#inspection","text":"Machinery inspects several parts of a system which are covered by Machinery's scopes. Information about scopes is listed here . Users of Machinery who inspect systems need to be aware of the security implications to take the right decisions on how to protect the retrieved data.","title":"Inspection"},{"location":"docs/machinery_main_security_implications.1/#retrieval-of-data","text":"Machinery transfers data from one end point to another via SSH (Secure Shell, using public key authentication). Depending on the scope, Machinery collects information about files on the system. Additionally, when the --extract-files option is given for the inspect command, not only the meta data about the files (e.g. permission bits, owner, group etc .) but also the file content is extracted. Machinery does not distinguish between sensitive data (such as private keys or password files). That means that everyone with access to the system description has automatically access to all extracted files and contained sensitive data.","title":"Retrieval of Data"},{"location":"docs/machinery_main_security_implications.1/#rootsudo-privileges","text":"An inspection can only be done, when the user on the inspected system is either root or has sudo privileges. Information about the required sudo configuration can be found here .","title":"root/sudo Privileges"},{"location":"docs/machinery_main_security_implications.1/#storage-of-data","text":"","title":"Storage of Data"},{"location":"docs/machinery_main_security_implications.1/#access-restrictions","text":"After an inspection has been completed, the directory where the description is stored is made readable only for the user. The data is not encrypted by Machinery.","title":"Access Restrictions"},{"location":"docs/machinery_main_security_implications.1/#used-permission-bits","text":"When Machinery extracts data, it sets permission bits for files and directories as follows: Permission Bits Used for ... 0700 ... directories inside the description directory 0600 ... for files inside the description directory","title":"Used Permission Bits"},{"location":"docs/machinery_main_security_implications.1/#accessing-system-descriptions","text":"By default, all system descriptions are stored in the directory .machinery in the home directory of the user running Machinery. The directory can be redefined by the environment variable $MACHINERY_DIR . Each description has its own subdirectory. There is a manifest.json file in each description directory which contains the data of the inspection. Extracted files are stored in separate subdirectories inside the same description directory.","title":"Accessing System Descriptions"},{"location":"docs/machinery_main_security_implications.1/#presentation-of-data","text":"There are several ways how data can be presented to one or more users. The user has the option to either start a web server and view descriptions or view the descriptions only in the console. The following commands are used to present data to users: show compare serve list All of the commands listed above also have a --html option. When this option is used, Machinery starts a web server what will listen on the IP address 127.0.0.1 . The serve command offers also a --public option which makes the server listen on all configured IP addresses. WARNING: When making the server reachable from the outside, users can modify the link to access also other descriptions. There is currently no way to restrict the access to only one description. The serve command also allows the user to specify a port via the --port option. When no port is specified, the default port which is configured in the machinery config file in ~/.machinery/machinery.config ) will be taken.","title":"Presentation of Data"},{"location":"docs/machinery_main_security_implications.1/#export-of-data","text":"","title":"Export of Data"},{"location":"docs/machinery_main_security_implications.1/#export-autoyast","text":"The export-autoyast command creates an AutoYaST profile for an automated installation. This will result in tar balls containing the extracted files from the system description. These files potentially contain sensitive data (e.g. passwords). This fact needs to be kept in mind, especially if these files are copied to a web server for an AutoYaST installation via HTTP.","title":"export-autoyast"},{"location":"docs/machinery_main_security_implications.1/#export-kiwi","text":"The program kiwi allows you to build OS images for deployment. Machinery gives you the opportunity to export a KIWI description. This description can be used to build an image via Kiwi. The export-kiwi command creates a directory, where it stores the Kiwi configuration and the files of a system description. These files potentially contain sensitive data (e.g. passwords).","title":"export-kiwi"},{"location":"docs/machinery_main_security_implications.1/#build","text":"The created image potentially contains sensitive data (e.g. passwords) from extracted files.","title":"build"},{"location":"docs/machinery_main_security_implications.1/#deploy","text":"The uploaded image potentially contains sensitive data (e.g. passwords) from extracted files.","title":"deploy"},{"location":"docs/machinery_main_usecases.1/","text":"Use Cases 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 environment.","title":"Use cases"},{"location":"docs/machinery_main_usecases.1/#use-cases","text":"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 environment.","title":"Use Cases"}]}