machinery-tool 1.21.0 → 1.22.0

data/manual/site/machinery_main_scopes.1/index.html

@@ -23,26 +23,29 @@
 
           
               
-                  <li>Home
-                      <ul>
-                      
-                          <li class="">
-                              <a href="../machinery_main_general.1/">General</a>
-                          </li>
-                      
-                          <li class="current">
-                              <a href="./">Scopes</a>
-                          </li>
-                      
-                          <li class="">
-                              <a href="../machinery_main_usecases.1/">Use cases</a>
-                          </li>
-                      
-                          <li class="">
-                              <a href="../machinery_security_implications.1/">Security Implications</a>
-                          </li>
-                      
-                      </ul>
+                  <li class="">
+                      <a href="../machinery_main_general.1/">General Overview</a>
+                  </li>
+              
+
+          
+              
+                  <li class="current">
+                      <a href="./">Scopes</a>
+                  </li>
+              
+
+          
+              
+                  <li class="">
+                      <a href="../machinery_main_usecases.1/">Use cases</a>
+                  </li>
+              
+
+          
+              
+                  <li class="">
+                      <a href="../machinery_main_security_implications.1/">Security Implications</a>
                   </li>
               
 
@@ -83,12 +86,16 @@
                               <a href="../machinery-export-kiwi.1/">Export Kiwi</a>
                           </li>
                       
+                          <li class="">
+                              <a href="../machinery-export-html.1/">Export HTML</a>
+                          </li>
+                      
                           <li class="">
                               <a href="../machinery-inspect.1/">Inspect</a>
                           </li>
                       
                           <li class="">
-                              <a href="../machinery-inspect-docker.1/">Inspect Docker</a>
+                              <a href="../machinery-inspect-container.1/">Inspect Container</a>
                           </li>
                       
                           <li class="">
@@ -131,7 +138,8 @@
         </ul>
       </div>
       <div class="content">
-        <ul>
+        <h1 id="scopes">Scopes</h1>
+<ul>
 <li>os</li>
 </ul>
 <p>Contains information about the operating system, name, version, and
@@ -139,25 +147,22 @@ architecture of the inspected system.</p>
 <ul>
 <li>packages</li>
 </ul>
-<p>Contains information on all installed RPM packages installed on the
+<p>Contains information on all installed packages installed on the
 inspected system.</p>
 <ul>
 <li>patterns</li>
 </ul>
 <p>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. Therefore, the pattern scope on SUSE based systems uses the
-<code>zypper</code> command to obtain the information about installed pattern names, whereas
-on Debian based systems the <code>tasksel</code> tool is necessary to list installed tasks.</p>
+like systems. The meaning of software patterns depends on the package manager of the
+distribution.</p>
 <ul>
 <li>repositories</li>
 </ul>
 <p>Contains all information about software repositories configured on the
 inspected system. The information about repositories depends on the package
-manager of the distribution. Thus on SUSE-based systems the <code>zypper</code> command
-is used. Machinery collects the following information from each configured repository:</p>
+manager of the distribution. Machinery collects the following information
+from each configured repository:</p>
 <ul>
 <li>
 <p>The alias name of the repository.</p>
@@ -208,7 +213,7 @@ runlevel. It uses the <code>chkconfig</code> command to obtain that information.
 The xinetd services that are also displayed by <code>chkconfig</code> are switched
 on/off by editing configuration files and are ignored in this context.</p>
 <ul>
-<li>changed_config_files</li>
+<li>changed-config-files</li>
 </ul>
 <p>Contains all configuration files which have been changed since they were
 installed.
@@ -217,22 +222,22 @@ 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.</p>
 <ul>
-<li>changed_managed_files</li>
+<li>changed-managed-files</li>
 </ul>
 <p>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.</p>
 <ul>
-<li>unmanaged_files</li>
+<li>unmanaged-files</li>
 </ul>
-<p>Contains the names and contents of all files which are not part of any RPM
-package. The list of unmanaged files contains only plain files and
+<p>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 <code>/tmp</code>,  <code>/var/tmp</code>, <code>/.snapshots/</code>,
 <code>/var/run</code> and special mounts like procfs and sysfs are ignored, too.
 If a directory is in this list, no file or directory below it belongs to a
-RPM package.</p>
+package.</p>
 <p>Meta data information of unmanaged files is only available if the files were
 extracted during inspection.</p>
 <p>Using the <code>--extract-unmanaged-files</code> option, the files are transferred from

data/manual/site/machinery_main_security_implications.1/index.html

@@ -0,0 +1,228 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8"/>
+    <link href="../custom.css" rel="stylesheet">
+  </head>
+  <body id="manpage">
+    <div id="back">
+      <a href="..">
+        <img src="../hand3.png" class="hand3"/>
+        <div class="goback">Go back to the web site</div>
+      </a>
+    </div>
+    <div class="mp">
+      <div class="nav">
+        <ul>
+          
+              
+                  <li class="">
+                      <a href="../docs/">Welcome</a>
+                  </li>
+              
+
+          
+              
+                  <li class="">
+                      <a href="../machinery_main_general.1/">General Overview</a>
+                  </li>
+              
+
+          
+              
+                  <li class="">
+                      <a href="../machinery_main_scopes.1/">Scopes</a>
+                  </li>
+              
+
+          
+              
+                  <li class="">
+                      <a href="../machinery_main_usecases.1/">Use cases</a>
+                  </li>
+              
+
+          
+              
+                  <li class="current">
+                      <a href="./">Security Implications</a>
+                  </li>
+              
+
+          
+              
+                  <li>Commands
+                      <ul>
+                      
+                          <li class="">
+                              <a href="../machinery-analyze.1/">Analyze</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-build.1/">Build</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-compare.1/">Compare</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-config.1/">Config</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-copy.1/">Copy</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-deploy.1/">Deploy</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-export-autoyast.1/">Export AutoYaST</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-export-kiwi.1/">Export Kiwi</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-export-html.1/">Export HTML</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-inspect.1/">Inspect</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-inspect-container.1/">Inspect Container</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-list.1/">List</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-man.1/">Man</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-move.1/">Move</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-remove.1/">Remove</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-serve.1/">Serve</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-show.1/">Show</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-upgrade-format.1/">Upgrade Format</a>
+                          </li>
+                      
+                          <li class="">
+                              <a href="../machinery-validate.1/">Validate</a>
+                          </li>
+                      
+                      </ul>
+                  </li>
+              
+
+          
+        </ul>
+      </div>
+      <div class="content">
+        <h1 id="security-implications">Security Implications</h1>
+<p>This document describes security related issues administrators need to be aware of when using
+Machinery.</p>
+<h2 id="inspection">Inspection</h2>
+<p>Machinery inspects several parts of a system which are covered by Machinery's scopes.
+Information about scopes is listed <a href="../machinery_main_scopes.1/">here</a>.</p>
+<p>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.</p>
+<h2 id="retrieval-of-data">Retrieval of Data</h2>
+<p>Machinery transfers data from one end point to another via SSH (Secure Shell, using public key authentication).</p>
+<p>Depending on the scope, Machinery <a href="../machinery_main_scopes.1/">collects information</a>
+about files on the system. Additionally, when the <code>--extract-files</code> option is given for the
+<code>inspect</code> 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 <strong>all</strong> extracted files and contained sensitive data.</p>
+<h4 id="rootsudo-privileges">root/sudo Privileges</h4>
+<p>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
+<a href="../machinery-inspect.1/#prerequisites">here</a>.</p>
+<h2 id="storage-of-data">Storage of Data</h2>
+<h4 id="access-restrictions">Access Restrictions</h4>
+<p>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.</p>
+<h4 id="used-permission-bits">Used Permission Bits</h4>
+<p>When Machinery extracts data, it sets permission bits for files and directories as follows:</p>
+<table>
+<thead>
+<tr>
+<th>Permission Bits</th>
+<th>Used for ...</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>0700</td>
+<td>... directories inside the description directory</td>
+</tr>
+<tr>
+<td>0600</td>
+<td>... for files inside the description directory</td>
+</tr>
+</tbody>
+</table>
+<h4 id="accessing-system-descriptions">Accessing System Descriptions</h4>
+<p>By default, all system descriptions are stored in the directory <code>.machinery</code> in the home directory
+of the user running Machinery. The directory can be redefined by the environment variable
+<code>$MACHINERY_DIR</code>. Each description has its own subdirectory. There is a <code>manifest.json</code> file in
+each description directory which contains the data of the inspection. Extracted files are stored in
+separate subdirectories inside the same description directory.</p>
+<h2 id="presentation-of-data">Presentation of Data</h2>
+<p>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.</p>
+<p>The following commands are used to present data to users:</p>
+<ul>
+<li>show</li>
+<li>compare</li>
+<li>serve</li>
+<li>list</li>
+</ul>
+<p>All of the commands listed above also have a <code>--html</code> option. When this option is used, Machinery
+starts a web server what will listen on the IP address <code>127.0.0.1</code>. The <code>serve</code> command
+offers also a <code>--public</code> option which makes the server listen on all configured IP addresses.</p>
+<p><strong>WARNING:</strong> 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.</p>
+<p>The <code>serve</code> command also allows the user to specify a port via the <code>--port</code> option. When no port
+is specified, the default port which is configured in the machinery config file in
+<code>~/.machinery/machinery.config</code>) will be taken.</p>
+<h2 id="export-of-data">Export of Data</h2>
+<h4 id="export-autoyast">export-autoyast</h4>
+<p>The <code>export-autoyast</code> 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.</p>
+<h4 id="export-kiwi">export-kiwi</h4>
+<p>The program <strong>kiwi</strong> 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 <code>export-kiwi</code> 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).</p>
+<h4 id="build">build</h4>
+<p>The created image potentially contains sensitive data (e.g. passwords) from extracted files.</p>
+<h4 id="deploy">deploy</h4>
+<p>The uploaded image potentially contains sensitive data (e.g. passwords) from extracted files.</p>
+      </div>
+    </div>
+  </body>
+</html>

data/manual/site/machinery_main_usecases.1/index.html

@@ -23,26 +23,29 @@
 
           
               
-                  <li>Home
-                      <ul>
-                      
-                          <li class="">
-                              <a href="../machinery_main_general.1/">General</a>
-                          </li>
-                      
-                          <li class="">
-                              <a href="../machinery_main_scopes.1/">Scopes</a>
-                          </li>
-                      
-                          <li class="current">
-                              <a href="./">Use cases</a>
-                          </li>
-                      
-                          <li class="">
-                              <a href="../machinery_security_implications.1/">Security Implications</a>
-                          </li>
-                      
-                      </ul>
+                  <li class="">
+                      <a href="../machinery_main_general.1/">General Overview</a>
+                  </li>
+              
+
+          
+              
+                  <li class="">
+                      <a href="../machinery_main_scopes.1/">Scopes</a>
+                  </li>
+              
+
+          
+              
+                  <li class="current">
+                      <a href="./">Use cases</a>
+                  </li>
+              
+
+          
+              
+                  <li class="">
+                      <a href="../machinery_main_security_implications.1/">Security Implications</a>
                   </li>
               
 
@@ -83,12 +86,16 @@
                               <a href="../machinery-export-kiwi.1/">Export Kiwi</a>
                           </li>
                       
+                          <li class="">
+                              <a href="../machinery-export-html.1/">Export HTML</a>
+                          </li>
+                      
                           <li class="">
                               <a href="../machinery-inspect.1/">Inspect</a>
                           </li>
                       
                           <li class="">
-                              <a href="../machinery-inspect-docker.1/">Inspect Docker</a>
+                              <a href="../machinery-inspect-container.1/">Inspect Container</a>
                           </li>
                       
                           <li class="">
@@ -131,18 +138,7 @@
         </ul>
       </div>
       <div class="content">
-        <h2 id="system-description">System Description</h2>
-<p>The System Description format and file structure is documented in the machinery
-wiki: <a href="https://github.com/SUSE/machinery/wiki/System-Description-Format">https://github.com/SUSE/machinery/wiki/System-Description-Format</a></p>
-<p>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</p>
-<p>To manually validate a description use the <code>machinery validate</code> command.</p>
-<h2 id="use-cases">Use Cases</h2>
+        <h1 id="use-cases">Use Cases</h1>
 <p>Some of the important use cases of Machinery are:</p>
 <ul>
 <li>Inspecting a System and Collecting Information</li>
@@ -161,21 +157,7 @@ can use the description</p>
 <p>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.</p>
-<h1 id="options-for-all-subcommands">OPTIONS FOR ALL SUBCOMMANDS</h1>
-<!--- These are 'global' options of machinery -->
-
-<ul>
-<li>
-<p><code>--version</code>:
-    Displays version of <code>machinery</code> tool. Exit when done.</p>
-</li>
-<li>
-<p><code>--debug</code>:
-    Enable debug mode. Machinery writes additional information into the log
-    file which can be useful to track down problems.</p>
-</li>
-</ul>
+  can then for example be deployed to a cloud environment.</p>
       </div>
     </div>
   </body>