adm_support.xml

<?xml version="1.0"?>
<!DOCTYPE chapter [
  <!ENTITY % entities SYSTEM "generic-entities.ent">
  %entities;
]>

<!--
   Interesting FATE entries:
   * #302163: A Bug Reporting Wizard
   * #303705: Unify system characterization tooling
     (SLED-11-SP1/SLES-11-SP1)
    According to the FATE entries, it seems the tools sitar, siga,
    and supportconfig will be obsolete in the future(?)
   * Diffing of Packages:
     osc co, apply patches with quilt for sp1 and sp2,
     -> mweckbecker, ptesarik

  Info Provider:
  * swehnert
  * jrecord
  * fhassel
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cha-adm-support">
<!-- support: sitar / onstar, siga, supportconfig -->
<!-- taroth 2014-04-24:   http://fate.suse.com/315699,
  http://bugzilla.suse.com/show_bug.cgi?id=871928-->
 <title>Gathering System Information for Support</title>
 <info>
  <meta name="description">Learn about accessing detailed system information, creating problem reports, and analyzing SupportConfig output with SUSE tools</meta>
  <abstract>
   <para>
    For a quick overview of all relevant system information of a machine,
    &productname; offers the
    <systemitem class="systemname">hostinfo</systemitem> package. It also helps
    system administrators to check for tainted kernels (that are not supported)
    or any third-party packages installed on a machine.
   </para>

   <para>
    In case of problems, a detailed system report may be created with either
    the <command>supportconfig</command> command line tool or the &yast;
    <guimenu>Support</guimenu> module. Both will collect information about the
    system such as: current kernel version, hardware, installed packages,
    partition setup, and much more. The result is a TAR archive of files. After
    opening a Service Request (SR), you can upload the TAR archive to Global
    Technical Support. It will help to locate the issue you reported and to
    assist you in solving the problem.
   </para>

   <para>
    Additionally, you can analyze the <command>supportconfig</command> output
    for known issues to help resolve problems faster. For this purpose,
    &productname; provides both an appliance and a command line tool for
    <literal>Supportconfig Analysis</literal> (SCA).
   </para>
  </abstract>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
   <dm:bugtracker/>
   <dm:translation>yes</dm:translation>
  </dm:docmanager>
 <revhistory xml:id="rh-cha-adm-support">
   <revision>
     <date>2026-04-09</date>
     <revdescription>
       <para/>
     </revdescription>
   </revision>
 </revhistory>
</info>
<!-- support: sitar / onstar, siga, supportconfig -->
 <sect1 xml:id="sec-admsupport-hostinfo">
  <title>Displaying Current System Information</title>

<!--<remark>toms 2014-03-12: FATE#315869</remark>-->

  <para>
   For a quick and easy overview of all relevant system information when
   logging in to a server, use the package
   <systemitem class="systemname">hostinfo</systemitem>. After it has been
   installed on a machine, the console displays the following information to
   any &rootuser; user that logs in to this machine:
  </para>

  <example xml:id="ex-support-hostinfo">
   <title>Output of <command>hostinfo</command> When Logging In as &rootuser;</title>
<screen>Hostname:                 &exampleclient;
Current As Of:            Fri 28 Sep 2018 03:18:57 PM CEST
Distribution:             SUSE Linux Enterprise Server 12
 -Service Pack:           4
Architecture:             x86_64
Kernel Version:           4.12.14-94.37-default
 -Installed:              Mon 24 Sep 2018 10:43:46 AM CEST
 -Status:                 Not Tainted
Last Updated Package:     Fri 28 Sep 2018 03:18:55 PM CEST
 -Patches Needed:         0
 -Security:               0
 -3rd Party Packages:     0
IPv4 Address:             eth0 &exampledomain1ip;.1
Total/Free/+Cache Memory: 1812/360/1275 MB (70% Free)
Hard Disk:                /dev/sda 32 GB</screen>
  </example>

  <para>
   In case the output shows a <literal>tainted</literal> kernel status, see
   <xref linkend="sec-admsupport-kernel"/> for more details.
  </para>
 </sect1>
 <sect1 xml:id="sec-admsupport-supportconfig">
  <title>Collecting System Information with Supportconfig</title>

  <para>
   To create a TAR archive with detailed system information that you can hand
   over to Global Technical Support, use either the
   <command>supportconfig</command> command line tool directly or the &yast;
   <guimenu>Support</guimenu> module. The command line tool is provided by the
   package <systemitem>supportutils</systemitem> which is installed by default.
   The &yast; <guimenu>Support</guimenu> module is also based on the command
   line tool.
  </para>

  <sect2 xml:id="sec-admsupport-supportconfig-sr">
   <title>Creating a Service Request Number</title>
   <para>
    Supportconfig archives can be generated at any time. However, for
    handing over the supportconfig data to Global Technical Support, you need
    to generate a service request number first. You will need it to upload the
    archive to support.
   </para>
   <para>
    To create a service request, go to
    <link xlink:href="https://scc.suse.com/support/requests"/> and follow the
    instructions on the screen. Write down your 12-digit service request
    number.
   </para>
   <note>
    <title>Privacy Statement</title>
    <para>
     &suse; and Micro Focus treat system reports as confidential data. For
     details about our privacy commitment, see <link xlink:href="https://www.suse.com/company/policies/privacy/"/>.
    </para>
   </note>
  </sect2>

  <sect2 xml:id="sec-admsupport-yast">
   <title>Creating a Supportconfig Archive with &yast;</title>
   <para>
    To use &yast; to gather your system information, proceed as follows:
    <remark>2008-11-20 toms: YaST asks the user to open a URL as
     root(!). This happens when the users clicks on "Open" (Open
     Support Center/ This will start a browser with
     Support Center Portal). I do not think we should describe this
     and only *use* the above URL as a normal user for security
     reasons.</remark>
   </para>
   <procedure>
    <step>
     <para>
      Start &yast; and open the <guimenu>Support</guimenu> module.
     </para>
     <informalfigure>
      <mediaobject>
       <textobject role="description">
        <phrase>&yast; support module</phrase>
       </textobject>
       <imageobject role="fo">
        <imagedata fileref="yast2-support-main.png" width="70%"/>
       </imageobject>
       <imageobject role="html">
        <imagedata fileref="yast2-support-main.png" width="60%"/>
       </imageobject>
      </mediaobject>
     </informalfigure>
    </step>
    <step>
     <para>
      Click <guimenu>Create report tarball</guimenu>.
     </para>
    </step>
    <step>
     <para>
      In the next window, select one of the supportconfig options from the
      radio button list. <guimenu>Use Custom (Expert) Settings</guimenu> is
      preselected by default. If you want to test the report function first,
      use <guimenu>Only gather a minimum amount of info</guimenu>. For some
      background information on the other options, refer to the
      <command>supportconfig</command> man page.
     </para>
     <para>
      Proceed with <guimenu>Next</guimenu>.
     </para>
    </step>
    <step xml:id="step-supportconfig-contact">
     <para>
      Enter your contact information. It will be written to a file called
      <filename>basic-environment.txt</filename> and included in the archive to
      be created.
     </para>
    </step>
    <step xml:id="step-supportconfig-upload-target">
     <para>
      If you want to submit the archive to Global Technical Support at the end
      of the information collection process, <guimenu>Upload
      Information</guimenu> is required. &yast; automatically proposes an
      upload server.
     </para>
     <para>
      If you want to submit the archive later on, you can leave the
      <guimenu>Upload Information</guimenu> empty for now.
     </para>
    </step>
    <step>
     <para>
      Proceed with <guimenu>Next</guimenu>.
     </para>
    </step>
    <step>
     <para>
      The information gathering begins.
     </para>
     <informalfigure>
      <mediaobject>
       <textobject role="description">
        <phrase>&yast; support configuration</phrase>
       </textobject>
       <imageobject role="fo">
        <imagedata fileref="yast2-support-conf.png" width="90%"/>
       </imageobject>
       <imageobject role="html">
        <imagedata fileref="yast2-support-conf.png" width="80%"/>
       </imageobject>
      </mediaobject>
     </informalfigure>
     <para>
      After the process is finished, continue with <guimenu>Next</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Review the data collection: Select the <guimenu>File Name</guimenu> of a
      log file to view its contents in &yast;. To remove any files you want
      excluded from the TAR archive before submitting it to support, use
      <guimenu>Remove from Data</guimenu>. Continue with
      <guimenu>Next</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Save the TAR archive. If you started the &yast; module as &rootuser;
      user, by default &yast; proposes to save the archive to
      <filename>/var/log</filename> (otherwise, to your home directory). The
      file name format is
      <filename>nts_<replaceable>HOST</replaceable>_<replaceable>DATE</replaceable>_<replaceable>TIME</replaceable>.tbz</filename>.
     </para>
    </step>
    <step>
     <para>
      If you want to upload the archive to support directly, make sure
      <guimenu>Upload log files tarball to URL</guimenu> is activated. The
      <guimenu>Upload Target</guimenu> shown here is the one that &yast;
      proposes in <xref linkend="step-supportconfig-upload-target"/>.
     </para>
    </step>
    <step>
     <para>
      If you want to skip the upload, deactivate <guimenu>Upload log files
      tarball to URL</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Confirm your changes to close the &yast; module.
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2 xml:id="sec-admsupport-cli">
   <title>Creating a Supportconfig Archive from Command Line</title>
   <para>
    The following procedure shows how to create a supportconfig archive, but
    without submitting it to support directly. For uploading it, you need to
    run the command with certain options as described in
    <xref linkend="pro-admsupport-submit-cli"/>.
   </para>
   <procedure>
    <step>
     <para>
      Open a shell and become <systemitem class="username">root</systemitem>.
     </para>
    </step>
    <step>
     <para>
      Run <command>supportconfig</command> without any options. This gathers
      the default system information.
     </para>
    </step>
    <step>
     <para>
      Wait for the tool to complete the operation.
     </para>
    </step>
    <step>
     <para>
      The default archive location is <filename>/var/log</filename>, with the
      file name format being
      <filename>nts_<replaceable>HOST</replaceable>_<replaceable>DATE</replaceable>_<replaceable>TIME</replaceable>.tbz</filename>
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2 xml:id="sec-admsupport-options">
   <title>Common Supportconfig Options</title>
   <para>
    The <command>supportconfig</command> utility is usually called without any
    options. Display a list of all options with
    <command>supportconfig</command> <option>-h</option> or refer to the man
    page. The following list gives a brief overview of some common use cases:
   </para>
   <variablelist>
    <varlistentry>
     <term>Reducing the Size of the Information Being Gathered</term>
     <listitem>
      <para>
       Use the minimal option (<option>-m</option>):
      </para>
<screen>supportconfig -m</screen>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Limiting the Information to a Specific Topic</term>
     <listitem>
      <para>
       If you have already localized a problem with the default
       <command>supportconfig</command> output and have found that it relates
       to a specific area or feature set only, you should limit the collected
       information to the specific area for the next
       <command>supportconfig</command> run. For example, if you detected
       problems with LVM and want to test a recent change that you did to the
       LVM configuration, it makes sense to gather the minimum supportconfig
       information around LVM only:
      </para>
<screen>supportconfig -i LVM</screen>
      <para>
       For a complete list of feature keywords that you can use for limiting
       the collected information to a specific area, run
      </para>
<screen>supportconfig -F</screen>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Including Additional Contact Information in the Output:</term>
     <listitem>
<screen>supportconfig -E tux@example.org -N "Tux Penguin" -O<!--
      --> "Penguin Inc." ...</screen>
      <para>
       (all in one line)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Collecting Already Rotated Log Files</term>
     <listitem>
<screen>supportconfig -l</screen>
      <para>
       This is especially useful in high logging environments or after a kernel
       crash when syslog rotates the log files after a reboot.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-admsupport-submit">
  <title>Submitting Information to Global Technical Support</title>

  <para>
   Use the &yast; <guimenu>Support</guimenu> module or the
   <command>supportconfig</command> command line utility to submit system
   information to the Global Technical Support. When you experience a server
   issue and want the support's assistance, you will need to open a service
   request first. For details, see
   <xref linkend="sec-admsupport-supportconfig-sr"/>.
  </para>

  <para>
   The following examples use <replaceable>12345678901</replaceable> as a
   placeholder for your service request number. Replace
   <replaceable>12345678901</replaceable> with the service request number you
   created in <xref linkend="sec-admsupport-supportconfig-sr"/>.
  </para>

  <procedure xml:id="pro-admsupport-submit-yast">
   <title>Submitting Information to Support with &yast;</title>
   <para>
    The following procedure assumes that you have already created a
    supportconfig archive, but have not uploaded it yet. Make sure to have
    included your contact information in the archive as described in
    <xref linkend="sec-admsupport-yast"/>,
    <xref linkend="step-supportconfig-contact" xrefstyle="select:label nopage"/>.
    For instructions on how to generate and submit a supportconfig archive in
    one go, see <xref linkend="sec-admsupport-yast"/>.
   </para>
   <step>
    <para>
     Start &yast; and open the <guimenu>Support</guimenu> module.
    </para>
   </step>
   <step>
    <para>
     Click <guimenu>Upload</guimenu>.
    </para>
   </step>
   <step>
    <para>
     In <guimenu>Package with log files</guimenu> specify the path to the
     existing supportconfig archive or <guimenu>Browse</guimenu> for it.
    </para>
   </step>
   <step xml:id="step-supportcfg-submit-upltarget">
    <para>
     &yast; automatically proposes an upload server.
    </para>
    <informalfigure>
     <mediaobject>
      <textobject role="description">
       <phrase>&yast; configuration upload</phrase>
      </textobject>
      <imageobject role="fo">
       <imagedata fileref="yast2-support-conf-upload.png" width="70%"/>
      </imageobject>
      <imageobject role="html">
       <imagedata fileref="yast2-support-conf-upload.png" width="60%"/>
      </imageobject>
     </mediaobject>
    </informalfigure>
    <para>
     <remark>taroth 2014-04-11: this does not make sense to me - why does the
      YaST module *not* ask for the SR number now? and lets you continue after
      specifying an upload target (but no RC or customer info)? I would
      expect it to *check* if an SR has been entered and otherwise show an error
      message - filed http://bugzilla.suse.com/show_bug.cgi?id=880943 for this, unfortunately it
      was rejected for technical reasons</remark>
     Proceed with <guimenu>Next</guimenu>.
    </para>
   </step>
   <step>
    <para>
     Click <guimenu>Finish</guimenu>.
    </para>
   </step>
  </procedure>

  <procedure xml:id="pro-admsupport-submit-cli">
   <title>Submitting Information to Support from Command Line</title>
   <para>
    The following procedure assumes that you have already created a
    supportconfig archive, but have not uploaded it yet. For instructions on
    how to generate and submit a supportconfig archive in one go, see
    <xref linkend="sec-admsupport-yast"/>.
   </para>
   <step>
    <para>
     Servers with Internet connectivity:
    </para>
    <substeps performance="required">
     <step>
      <para>
       To use the default upload target, run:
      </para>
<screen>supportconfig -ur <replaceable>12345678901</replaceable></screen>
     </step>
     <step>
      <para>
       For the secure upload target, use the following:
      </para>
<!--taroth 2014-04-04: bnc#871918-->
<screen>supportconfig -ar <replaceable>12345678901</replaceable></screen>
     </step>
    </substeps>
   </step>
   <step>
    <para>
     Servers <emphasis>without</emphasis> Internet connectivity
    </para>
    <substeps performance="required">
     <step>
      <para>
       Run the following:
      </para>
<screen>supportconfig -r <replaceable>12345678901</replaceable></screen>
     </step>
     <step>
      <para>
       Manually upload the
       <filename>/var/log/nts_<replaceable>SR12345678901</replaceable>*tbz</filename>
       archive to one of our FTP servers. For more information, see the man page
       of <command>supportconfig</command>.
      </para>
     </step>
    </substeps>
   </step>
   <step>
    <para>
     After the TAR archive arrives in the incoming directory of our FTP server,
     it becomes automatically attached to your service request.
    </para>
   </step>
  </procedure>
 </sect1>
<!-- taroth 2014-04-24:   http://fate.suse.com/315699,
  http://bugzilla.suse.com/show_bug.cgi?id=871928-->
 <sect1 xml:id="sec-admsupport-sca">
  <title>Analyzing System Information</title>

  <para>
   System reports created with <command>supportconfig</command> can be analyzed
   for known issues to help resolve problems faster. For this purpose,
   &productname; provides both an appliance and a command line tool for
   <literal>Supportconfig Analysis</literal> (SCA). The SCA appliance is a
   server-side tool which is non-interactive. The SCA tool
   (<command>scatool</command>) runs on the client-side and is executed from
   command line. Both tools analyze supportconfig archives from affected
   servers. The initial server analysis takes place on the SCA appliance or the
   workstation on which scatool is running. No analysis cycles happen on the
   production server.
  </para>

  <para>
   Both the appliance and the command line tool additionally need
   product-specific patterns that enable them to analyze the supportconfig
   output for the associated products. Each pattern is a script that parses and
   evaluates a supportconfig archive for one known issue. The patterns are
   available as RPM packages.
  </para>

  <para>
   For example, if you want to analyze supportconfig archives that have been
   generated on a &sle; 11 machine, you need to install the package
   <systemitem class="resource">sca-patterns-sle11</systemitem> together with
   the SCA tool (or on the machine that you want to use as the SCA appliance
   server). To analyze supportconfig archives generated on a &sle; 10 machine,
   you need the package
   <systemitem class="resource">sca-patterns-sle10</systemitem>.
  </para>

  <para>
   You can also develop your own patterns as briefly described in
   <xref linkend="sec-admsupport-sca-patterns"/>.
  </para>

  <sect2 xml:id="sec-admsupport-sca-tool">
   <title>SCA Command Line Tool</title>
   <para>
    The SCA command line tool lets you analyze a local machine using both
    <command>supportconfig</command> and the analysis patterns for the specific
    product that is installed on the local machine. The tool creates an HTML
    report showing its analysis results. For an example, see
    <xref linkend="fig-scatool-html"/>.
   </para>
   <figure xml:id="fig-scatool-html">
    <title>HTML Report Generated by SCA Tool</title>
    <mediaobject>
     <imageobject role="fo">
      <imagedata fileref="sca_tool_report_html.png" width="100%"/>
     </imageobject>
     <imageobject role="html">
      <imagedata fileref="sca_tool_report_html.png" width="100%"/>
     </imageobject>
    </mediaobject>
   </figure>
   <para>
    The <command>scatool</command> command is provided by the
    <systemitem class="resource">sca-server-report</systemitem> package. It is
    not installed by default. Additionally, you need the
    <systemitem class="resource">sca-patterns-base</systemitem> package and any
    of the product-specific
    <systemitem class="resource">sca-patterns-*</systemitem> packages that
    matches the product installed on the machine where you want to run the
    <command>scatool</command> command.
   </para>
   <para>
    Execute the <command>scatool</command> command either as &rootuser; user or
    with <command>sudo</command>. When calling the SCA tool, you can either
    analyze an existing <command>supportconfig</command> TAR archive or you can
    let it generate and analyze a new archive in one go. The tool also provides
    an interactive console (with tab completion) and the possibility to run
    <command>supportconfig</command> on an external machine and to execute the
    subsequent analysis on the local machine.
   </para>
   <para>
    Find some example commands below:
   </para>
   <variablelist>
    <varlistentry>
     <term><command>sudo scatool</command><option>-s</option>
     </term>
     <listitem>
      <para>
       Calls <command>supportconfig</command> and generates a new supportconfig
       archive on the local machine. Analyzes the archive for known issues by
       applying the SCA analysis patterns that match the installed product.
       Displays the path to the HTML report that is generated from the results
       of the analysis. It is usually written to the same directory where the
       supportconfig archive can be found.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><command>sudo scatool&nbsp;</command><option>-s</option>&nbsp;<option>-o</option>&nbsp;<replaceable>/opt/sca/reports/</replaceable>&nbsp;
     </term>
     <listitem>
      <para>
       Same as <command>sudo scatool</command> <option>-s</option>, only that
       the HTML report is written to the path specified with
       <option>-o</option>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><command>sudo scatool&nbsp;</command><option>-a</option>&nbsp;<replaceable>PATH_TO_TARBALL_OR_DIR</replaceable>&nbsp;
     </term>
     <listitem>
      <para>
       Analyzes the specified supportconfig archive file (or the specified
       directory to where the supportconfig archive has been extracted). The
       generated HTML report is saved in the same location as the supportconfig
       archive or directory.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><command>sudo scatool&nbsp;</command><option>-a</option>&nbsp;<replaceable>SLES_SERVER.COMPANY.COM</replaceable>&nbsp;
     </term>
     <listitem>
      <para>
       Establishes an SSH connection to an external server
       <replaceable>SLES_SERVER.COMPANY.COM</replaceable> and runs
       <command>supportconfig</command> on the server. The supportconfig
       archive is then copied back to the local machine and is analyzed there.
       The generated HTML report is saved to the default
       <filename>/var/log</filename> directory. (Only the supportconfig archive
       is created on <replaceable>SLES_SERVER.COMPANY.COM</replaceable>).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><command>sudo scatool</command><option>-c</option>
     </term>
     <listitem>
      <para>
       Starts the interactive console for <command>scatool</command>. Press
       <keycap function="tab"/> twice to see the available commands.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    For further options and information, run <command>sudo scatool -h</command>
    or see the <command>scatool</command> man page.
   </para>
  </sect2>

  <sect2 xml:id="sec-admsupport-sca-appliance">
   <title>SCA Appliance</title>
   <para>
    If you decide to use the SCA appliance for analyzing the supportconfig
    archives, you need to configure a dedicated server (or virtual machine) as
    the SCA appliance server. The SCA appliance server can then be used to
    analyze supportconfig archives from all machines in your enterprise running
    &sls; or &sled;. You can simply upload supportconfig archives to the
    appliance server for analysis. Interaction is not required. In a MariaDB
    database, the SCA appliance keeps track of all supportconfig archives that
    have been analyzed . You can read the SCA reports directly from the
    appliance Web interface. Alternatively, you can have the appliance send the
    HTML report to any administrative user via e-mail. For details, see
    <xref linkend="sec-admsupport-sca-appliance-config-mail"/>.
   </para>
   <sect3 xml:id="sec-admsupport-sca-appliance-installquick">
    <title>Installation Quick Start</title>
    <para>
     To install and set up the SCA appliance in a very fast way from the
     command line, follow the instructions here. The procedure is intended for
     experts and focuses on the bare installation and setup commands. For more
     information, refer to the more detailed description in
     <xref linkend="sec-admsupport-sca-appliance-pre"/> to
     <xref linkend="sec-admsupport-sca-appliance-install"/>.
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <title>Prerequisites</title>
     <listitem>
      <para>
       Web and LAMP Pattern
      </para>
     </listitem>
     <listitem>
      <para>
       Web and Scripting Module (you must register the machine to be able to
       select this module).
      </para>
     </listitem>
    </itemizedlist>
    <note>
     <title>&rootuser; Privileges Required</title>
     <para>
      All commands in the following procedure must be run as &rootuser;.
     </para>
    </note>
    <procedure>
     <title>Installation Using Anonymous FTP for Upload</title>
     <para>
      After the appliance is set up and running, no more manual interaction is
      required. This way of setting up the appliance is therefore ideal for
      using cron jobs to create and upload supportconfig archives.
     </para>
     <step>
      <para>
       On the machine on which to install the appliance, log in to a console
       and execute the following commands:
      </para>
<screen>zypper install sca-appliance-* sca-patterns-* vsftpd
systemctl enable apache2
systemctl start apache2
systemctl enable vsftpd
systemctl start vsftpd
yast ftp-server</screen>
     </step>
     <step>
      <para>
       In &yast; FTP Server, select <menuchoice>
       <guimenu>Authentication</guimenu> <guimenu>Enable Upload</guimenu>
       <guimenu>Anonymous Can Upload</guimenu> <guimenu>Finish</guimenu>
       <guimenu>Yes</guimenu> </menuchoice> to <guimenu>Create
       /srv/ftp/upload</guimenu>.
      </para>
     </step>
     <step>
      <para>
       Execute the following commands:
      </para>
<screen>systemctl enable mysql
systemctl start mysql
mysql_secure_installation
setup-sca -f</screen>
      <para>
       The mysql_secure_installation will create a MariaDB &rootuser; password.
      </para>
     </step>
    </procedure>
    <procedure>
     <title>Installation Using SCP/tmp for Upload</title>
     <para>
      This way of setting up the appliance requires manual interaction when
      typing the SSH password.
     </para>
     <step>
      <para>
       On the machine on which to install the appliance, log in to a console.
      </para>
     </step>
     <step>
      <para>
       Execute the following commands:
      </para>
<screen>zypper install sca-appliance-* sca-patterns-*
systemctl enable apache2
systemctl start apache2
sudo systemctl enable mysql
systemctl start mysql
mysql_secure_installation
setup-sca</screen>
     </step>
    </procedure>
   </sect3>
   <sect3 xml:id="sec-admsupport-sca-appliance-pre">
    <title>Prerequisites</title>
    <para>
     To run an SCA appliance server, you need the following prerequisites:
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <listitem>
      <para>
       All <systemitem>sca-appliance-*</systemitem> packages.
      </para>
     </listitem>
     <listitem>
      <para>
       The <systemitem class="resource">sca-patterns-base</systemitem> package.
       Additionally, any of the product-specific
       <systemitem class="resource">sca-patterns-*</systemitem> for the type of
       supportconfig archives that you want to analyze with the appliance.
      </para>
     </listitem>
     <listitem>
      <para>
       Apache
      </para>
     </listitem>
     <listitem>
      <para>
       PHP
      </para>
     </listitem>
     <listitem>
      <para>
       MariaDB
      </para>
     </listitem>
     <listitem>
      <para>
       anonymous FTP server (optional)
      </para>
     </listitem>
    </itemizedlist>
   </sect3>
   <sect3 xml:id="sec-admsupport-sca-appliance-install">
    <title>Installation and Basic Setup</title>
    <para>
     As listed in <xref linkend="sec-admsupport-sca-appliance-pre"/>, the SCA
     appliance has several dependencies on other packages. Therefore you need
     do so some preparations before installing and setting up the SCA appliance
     server:
    </para>
    <procedure>
     <step>
      <para>
       For Apache and MariaDB, install the <systemitem>Web</systemitem> and
       <systemitem>LAMP</systemitem> installation patterns.
      </para>
     </step>
     <step>
      <para>
       Set up Apache, MariaDB, and optionally an anonymous FTP server.
       <phrase os="sles"> For more information, see
       <xref linkend="cha-apache2"/> and <xref linkend="cha-ftp"/>. </phrase>
      </para>
     </step>
     <step>
      <para>
       Configure Apache and MariaDB to start at boot time:
      </para>
<screen>sudo systemctl enable apache2 mysql</screen>
     </step>
     <step>
      <para>
       Start both services:
      </para>
<screen>sudo systemctl start apache2 mysql</screen>
     </step>
    </procedure>
    <para>
     Now you can install the SCA appliance and set it up as described in
     <xref linkend="pro-sca-appl-install"/>.
    </para>
    <procedure xml:id="pro-sca-appl-install">
     <title>Installing and Configuring the SCA Appliance</title>
     <para>
      After installing the packages, use the <command>setup-sca</command>
      script for the basic configuration of the MariaDB administration and
      report database that is used by the SCA appliance.
     </para>
     <para>
      It can be used to configure the following options you have for uploading
      the supportconfig archives from your machines to the SCA appliance:
     </para>
     <itemizedlist mark="bullet" spacing="normal">
      <listitem>
       <para>
        <command>scp</command>
       </para>
      </listitem>
      <listitem>
       <para>
        anonymous FTP server
       </para>
      </listitem>
     </itemizedlist>
     <step>
      <para>
       Install the appliance and the SCA base-pattern library:
      </para>
<screen>sudo zypper install sca-appliance-* sca-patterns-base</screen>
     </step>
     <step>
      <para>
       Additionally, install the pattern packages for the types of
       supportconfig archives you want to analyze. For example, if you have
       &sls; 11 and &sls; 12 servers in your environment, install both the
       <systemitem>sca-patterns-sle11</systemitem> and
       <systemitem>sca-patterns-sle12</systemitem> packages.
      </para>
      <para>
       To install all available patterns:
      </para>
<screen>zypper install sca-patterns-*</screen>
     </step>
     <step>
      <para>
       For basic setup of the SCA appliance, use the
       <command>setup-sca</command> script. How to call it depends on how you
       want to upload the supportconfig archives to the SCA appliance server:
      </para>
      <itemizedlist mark="bullet" spacing="normal">
       <listitem>
        <para>
         If you have configured an anonymous FTP server that uses the
         <filename>/srv/ftp/upload</filename> directory, execute the setup
         script with the <option>-f</option> option and follow the instructions
         on the screen:
        </para>
<screen>setup-sca -f</screen>
        <note>
         <title>FTP Server Using Another Directory</title>
         <para>
          If your FTP server uses another directory than
          <filename>/srv/ftp/upload</filename>, adjust the following
          configuration files first to make them point to the correct
          directory: <filename>/etc/sca/sdagent.conf</filename> and
          <filename>/etc/sca/sdbroker.conf</filename> .
         </para>
        </note>
       </listitem>
       <listitem>
        <para>
         If you want to upload supportconfig files to the
         <filename>/tmp</filename> directory of the SCA appliance server via
         <command>scp</command>, call the setup script without any parameters
         and follow the instructions on the screen:
        </para>
<screen>setup-sca</screen>
       </listitem>
      </itemizedlist>
      <para>
       The setup script runs a few checks regarding its requirements and
       configures the needed components. It will prompt you for two passwords:
       the MySQL &rootuser; password of the MariaDB that you have set up, and a
       Web user password with which to log in to the Web interface of the SCA
       appliance.
      </para>
     </step>
     <step>
      <para>
       Enter the existing MariaDB &rootuser; password. It will allow the SCA
       appliance to connect to the MariaDB.
      </para>
     </step>
     <step>
      <para>
       Define a password for the Web user. It will be written to
       <filename>/srv/www/htdocs/sca/web-config.php</filename> and will be set
       as the password for the user
       <systemitem class="username">scdiag</systemitem>. Both user name and
       password can be changed at any time later, see
       <xref linkend="sec-admsupport-sca-appliance-config-passwd"/>.
      </para>
<!--taroth 2014-05-02: additional info in bnc#876021#c3:
       setup-sca accepts a "-w <str> Web user password" to set the password without
       being prompted if they want.-->
     </step>
    </procedure>
    <para>
     After successful installation and setup, the SCA appliance is ready for
     use, see <xref linkend="sec-admsupport-sca-appliance-use"/>. However, you
     should modify some options such as changing the password for the Web
     interface, changing the source for the SCA pattern updates, enabling
     archiving mode or configuring e-mail notifications. For details on that,
     see <xref linkend="sec-admsupport-sca-appliance-config"/>.
    </para>
    <warning>
     <title>Data Protection</title>
     <para>
      As the reports on the SCA appliance server contain security-relevant
      information of the machines whose supportconfig archives have been
      analyzed, make sure to protect the data on the SCA appliance server
      against unauthorized access.
     </para>
    </warning>
   </sect3>
   <sect3 xml:id="sec-admsupport-sca-appliance-use">
    <title>Using the SCA Appliance</title>
    <para>
     You can upload existing supportconfig archives to the SCA appliance
     manually or create new supportconfig archives and upload them to the SCA
     appliance in one step. Uploading can be done via FTP or SCP. For both, you
     need to know the URL where the SCA appliance can be reached. For upload
     via FTP, an FTP server needs to be configured for the SCA appliance, see
     <xref linkend="pro-sca-appl-install"/>.
    </para>
    <sect4 xml:id="sec-admsupport-sca-appliance-use-upload">
     <title>Uploading Supportconfig Archives to the SCA Appliance</title>
     <para/>
     <itemizedlist mark="bullet" spacing="normal">
      <listitem>
       <para>
        For creating a supportconfig archive and uploading it via (anonymous)
        FTP:
       </para>
<screen>sudo supportconfig -U “ftp://<replaceable>SCA-APPLIANCE.COMPANY.COM</replaceable>/upload”</screen>
      </listitem>
      <listitem>
       <para>
        For creating a supportconfig archive and uploading it via SCP:
       </para>
<screen>sudo supportconfig -U “scp://<replaceable>SCA-APPLIANCE.COMPANY.COM</replaceable>/tmp”</screen>
       <para>
        You will be prompted for the &rootuser; user password of the server
        running the SCA appliance.
       </para>
      </listitem>
      <listitem>
       <para>
        If you want to manually upload one or multiple archives, copy the
        existing archive files (usually located
        at<filename>/var/log/nts_*.tbz</filename>) to the SCA appliance. As
        target, use either the appliance server's <filename>/tmp</filename>
        directory or the <filename>/srv/ftp/upload</filename> directory (if FTP
        is configured for the SCA appliance server).
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
    <sect4 xml:id="sec-admsupport-sca-appliance-use-view">
     <title>Viewing SCA Reports</title>
     <para>
      SCA reports can be viewed from any machine that has a browser installed
      and can access the report index page of the SCA appliance.
     </para>
     <procedure>
      <step>
       <para>
        Start a Web browser and make sure that JavaScript and cookies are
        enabled.
       </para>
      </step>
      <step>
       <para>
        As a URL, enter the report index page of the SCA appliance.
       </para>
<screen>https://sca-appliance.company.com/sca</screen>
       <para>
        If in doubt, ask your system administrator.
       </para>
      </step>
      <step>
       <para>
        You will be prompted for a user name and a password to log in.
       </para>
       <figure xml:id="fig-sca-appl-html">
        <title>HTML Report Generated by SCA Appliance</title>
        <mediaobject>
         <imageobject role="fo">
          <imagedata fileref="sca_appl_report_html.png" width="100%"/>
         </imageobject>
         <imageobject role="html">
          <imagedata fileref="sca_appl_report_html.png" width="100%"/>
         </imageobject>
        </mediaobject>
       </figure>
      </step>
      <step>
       <para>
        After logging in, click the date of the report you want to read.
       </para>
      </step>
      <step>
       <para>
        Click the <guimenu>Basic Health</guimenu> category first to expand it.
       </para>
      </step>
      <step>
       <para>
        In the <guimenu>Message</guimenu> column, click an individual entry.
<!--pattern result title-->
        This opens the corresponding article in the &suse; Knowledgebase. Read
        the proposed solution and follow the instructions.
       </para>
      </step>
      <step>
       <para>
        If the <guimenu>Solutions</guimenu> column of the
        <guimenu>Supportconfig Analysis Report</guimenu> shows any additional
        entries, click them. Read the proposed solution and follow the
        instructions.
       </para>
      </step>
      <step>
       <para>
        Check the &suse; Knowledge base
        (<link xlink:href="https://www.suse.com/support/kb/"/>) for results that
        directly relate to the problem identified by SCA. Work at resolving
        them.
       </para>
      </step>
      <step>
       <para>
        Check for results that can be addressed proactively to avoid future
        problems.
       </para>
      </step>
     </procedure>
    </sect4>
   </sect3>
   <sect3 xml:id="sec-admsupport-sca-appliance-config">
    <title>Customizing the SCA Appliance</title>
    <para>
     The following sections show how to change the password for the Web
     interface, how to change the source for the SCA pattern updates, how to
     enable archiving mode, and how to configure e-mail notifications.
    </para>
    <sect4 xml:id="sec-admsupport-sca-appliance-config-passwd">
     <title>Password for the Web Interface</title>
     <para>
      The SCA Appliance Web interface requires a user name and password for
      logging in. The default user name is <literal>scdiag</literal> and the
      default password is <literal>linux</literal> (if not specified otherwise,
      see <xref linkend="pro-sca-appl-install"/>). Change the default password
      to a secure password at the earliest possibility. You can also modify the
      user name.
     </para>
     <procedure xml:id="pro-sca-passwd-change">
      <title>Changing User Name or Password for the Web Interface</title>
      <step>
       <para>
        Log in as &rootuser; user at the system console of the SCA appliance
        server.
       </para>
      </step>
      <step>
       <para>
        Open <filename>/srv/www/htdocs/sca/web-config.php</filename> in an
        editor.
       </para>
      </step>
      <step>
       <para>
        Change the values of <literal>$username</literal> and
        <literal>$password</literal> as desired.
       </para>
      </step>
      <step>
       <para>
        Save the file and exit.
       </para>
      </step>
     </procedure>
    </sect4>
    <sect4 xml:id="sec-admsupport-sca-appliance-config-upd">
     <title>Updates of SCA Patterns</title>
     <para>
      By default, all <systemitem class="resource">sca-patterns-*</systemitem>
      packages are updated regularly by a &rootuser; cron job that executes the
      <filename>sdagent-patterns</filename> script nightly, which in turn runs
      <command>zypper update sca-patterns-*</command>. A regular system update
      will update all SCA appliance and pattern packages. To update the SCA
      appliance and patterns manually, run:
     </para>
<screen>sudo zypper update sca-*</screen>
     <para>
      The updates are installed from the &sle; &productnumber; update
      repository by default. You can change the source for the updates to an
      &smt; server, if desired. When <filename>sdagent-patterns</filename> runs
      <command>zypper update sca-patterns-*</command>, it gets the updates from
      the currently configured update channel. If that channel is located on an
      &smt; server, the packages will be pulled from there.
     </para>
     <procedure>
      <title>Disabling Automatic Updates of SCA Patterns</title>
      <step>
       <para>
        Log in as &rootuser; user at the system console of the SCA appliance
        server.
       </para>
      </step>
      <step>
       <para>
<!--taroth 2014-04-09: this file does not exist on my test
         VM (which still runs a beta3) - is that a packaging error or perhaps a
         typo in your document? - bnc#876030: This file is new and will be included in Beta6. -->
        Open <filename>/etc/sca/sdagent-patterns.conf</filename> in an editor.
       </para>
      </step>
      <step>
       <para>
        Change the entry
       </para>
<screen>UPDATE_FROM_PATTERN_REPO=1</screen>
       <para>
        to
       </para>
<screen>UPDATE_FROM_PATTERN_REPO=0</screen>
      </step>
      <step>
       <para>
        Save the file and exit. The machine does not require any restart to
        apply the change.
       </para>
      </step>
     </procedure>
    </sect4>
    <sect4 xml:id="sec-admsupport-sca-appliance-config-archive">
     <title>Archiving Mode</title>
     <para>
      All supportconfig archives are deleted from the SCA appliance after they
      have been analyzed and their results have been stored in the MariaDB
      database. However, for troubleshooting purposes it can be useful to keep
      copies of supportconfig archives from a machine. By default, archiving
      mode is disabled.
     </para>
     <procedure>
      <title>Enabling Archiving Mode in the SCA Appliance</title>
      <step>
       <para>
        Log in as &rootuser; user at the system console of the SCA appliance
        server.
       </para>
      </step>
      <step>
       <para>
        Open <filename>/etc/sca/sdagent.conf</filename> in an editor.
       </para>
      </step>
      <step>
       <para>
        Change the entry
       </para>
<screen>ARCHIVE_MODE=0</screen>
       <para>
        to
       </para>
<screen>ARCHIVE_MODE=1</screen>
      </step>
      <step>
       <para>
        Save the file and exit. The machine does not require any restart to
        apply the change.
       </para>
      </step>
     </procedure>
     <para>
      After having enabled archive mode, the SCA appliance will save the
      supportconfig files to the <filename>/var/log/archives/saved</filename>
      directory, instead of deleting them.
     </para>
    </sect4>
    <sect4 xml:id="sec-admsupport-sca-appliance-config-mail">
     <title>Sending SCA Reports via E-Mail</title>
     <para>
      The SCA appliance can e-mail a report HTML file for each supportconfig
      analyzed. This feature is disabled by default. When enabling it, you can
      define a list of e-mail addresses to which the reports should be sent,
      and define a level of status messages that trigger the sending of reports
      (<literal>STATUS_NOTIFY_LEVEL</literal>).
     </para>
     <variablelist xml:id="vl-sca-mails-notify-level">
      <title>Possible Values for <literal>STATUS_NOTIFY_LEVEL</literal></title>
      <varlistentry>
       <term>$STATUS_OFF</term>
       <listitem>
        <para>
         Deactivate sending of HTML reports.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>$STATUS_CRITICAL</term>
       <listitem>
        <para>
         Send only SCA reports that include a CRITICAL.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>$STATUS_WARNING </term>
       <listitem>
        <para>
         Send only SCA reports that include a WARNING or CRITICAL.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>$STATUS_RECOMMEND</term>
       <listitem>
        <para>
         Send only SCA reports that include a RECOMMEND, WARNING or CRITICAL.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>$STATUS_SUCCESS</term>
       <listitem>
        <para>
         Send SCA reports that include a SUCCESS, RECOMMEND, WARNING or
         CRITICAL.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
     <procedure>
      <title>Configuring E-Mail Notifications for SCA Reports</title>
      <step>
       <para>
        Log in as &rootuser; user at the system console of the SCA appliance
        server.
       </para>
      </step>
      <step>
       <para>
        Open <filename>/etc/sca/sdagent.conf</filename> in an editor.
       </para>
      </step>
      <step>
       <para>
        Search for the entry <systemitem>STATUS_NOTIFY_LEVEL</systemitem>. By
        default, it is set to <literal>$STATUS_OFF</literal> (e-mail
        notifications are disabled).
       </para>
      </step>
      <step>
       <para>
        To enable e-mail notifications, change <literal>$STATUS_OFF</literal>
        to the level of status messages that you want to have e-mail reports
        for, for example:
       </para>
<screen>STATUS_NOTIFY_LEVEL=$STATUS_SUCCESS</screen>
       <para>
        For details, see <xref linkend="vl-sca-mails-notify-level"/>.
       </para>
      </step>
      <step>
       <para>
        To define the list of recipients to which the reports should be sent:
       </para>
       <substeps performance="required">
        <step>
         <para>
          Search for the entry <literal>EMAIL_REPORT='root'</literal>.
         </para>
        </step>
        <step>
         <para>
          Replace <literal>root</literal> with a list of e-mail addresses to
          which SCA reports should be sent. The e-mail addresses must be
          separated by spaces. For example:
         </para>
<screen>EMAIL_REPORT='&exampleuser_plain;@my.company.com&nbsp;&exampleuserII_plain;@your.company.com'</screen>
        </step>
       </substeps>
      </step>
      <step>
       <para>
        Save the file and exit. The machine does not require any restart to
        apply the changes. All future SCA reports will be e-mailed to the
        specified addresses.
       </para>
      </step>
     </procedure>
    </sect4>
   </sect3>
   <sect3 xml:id="sec-admsupport-sca-appliance-backup">
    <title>Backing Up and Restoring the Database</title>
    <para>
     To back up and restore the MariaDB database that stores the SCA reports,
     use the <command>scadb</command> command as described below.
    </para>
    <procedure>
     <title>Backing Up the Database</title>
     <step>
      <para>
       Log in as &rootuser; user at the system console of the server running
       the SCA appliance.
      </para>
     </step>
     <step>
      <para>
       Put the appliance into maintenance mode by executing:
      </para>
<screen>scadb maint</screen>
     </step>
     <step>
      <para>
       Start the backup with:
      </para>
<screen>scadb backup</screen>
      <para>
       The data is saved to a TAR archive:
       <filename>sca-backup-*sql.gz</filename>.
      </para>
     </step>
     <step>
      <para>
       If you are using the pattern creation database to develop your own
       patterns (see <xref linkend="sec-admsupport-sca-patterns"/>), back up
       this data, too:
      </para>
<screen>sdpdb backup</screen>
      <para>
       The data is saved to a TAR archive:
       <filename>sdp-backup-*sql.gz</filename>.
      </para>
     </step>
     <step>
      <para>
       Copy the following data to another machine or an external storage
       medium:
      </para>
      <itemizedlist mark="bullet" spacing="normal">
       <listitem>
        <para>
         <filename>sca-backup-*sql.gz</filename>
        </para>
       </listitem>
       <listitem>
        <para>
         <filename>sdp-backup-*sql.gz</filename>
        </para>
       </listitem>
       <listitem>
        <para>
         <filename>/usr/lib/sca/patterns/local</filename> (only needed if you
         have created custom patterns)
        </para>
       </listitem>
      </itemizedlist>
     </step>
     <step>
      <para>
       Reactivate the SCA appliance with:
      </para>
<screen>scadb reset agents</screen>
     </step>
    </procedure>
    <procedure>
     <title>Restoring the Database</title>
     <para>
      To restore the database from your backup, proceed as follows:
     </para>
     <step>
      <para>
       Log in as &rootuser; user at the system console of the server running
       the SCA appliance.
      </para>
     </step>
     <step>
      <para>
       Copy the newest <filename>sca-backup-*sql.gz</filename> and
       <filename>sdp-backup-*sql.gz</filename> TAR archives to the SCA
       appliance server.
      </para>
     </step>
     <step>
      <para>
       To decompress the files, run:
      </para>
<screen>gzip -d *-backup-*sql.gz</screen>
     </step>
     <step>
      <para>
       To import the data into the database, execute:
      </para>
<screen>scadb import sca-backup-*sql</screen>
     </step>
     <step>
      <para>
       If you are using the pattern creation database to create your own
       patterns, also import the following data with:
      </para>
<screen>sdpdb import sdp-backup-*sql</screen>
     </step>
     <step>
      <para>
       If you are using custom patterns, also restore
       <filename>/usr/lib/sca/patterns/local</filename> from your backup data.
      </para>
     </step>
     <step>
      <para>
       Reactivate the SCA appliance with:
      </para>
<screen>scadb reset agents</screen>
     </step>
     <step>
      <para>
       Update the pattern modules in the database with:
      </para>
<screen>sdagent-patterns -u</screen>
     </step>
    </procedure>
   </sect3>
  </sect2>

  <sect2 xml:id="sec-admsupport-sca-patterns">
   <title>Developing Custom Analysis Patterns</title>
   <para>
    The SCA appliance comes with a complete pattern development environment
    (the SCA Pattern Database) that enables you to develop your own, custom
    patterns. Patterns can be written in any programming language. To make them
    available for the supportconfig analysis process, they need to be saved to
    <filename>/usr/lib/sca/patterns/local</filename> and to be made executable.
    Both the SCA appliance and the SCA tool will then run the custom patterns
    against new supportconfig archives as part of the analysis report. For
    detailed instructions on how to create (and test) your own patterns, see
    <link xlink:href="https://www.suse.com/c/blog/sca-pattern-development/"/>.
   </para>
  </sect2>
 </sect1>

 <sect1 xml:id="sec-admsupport-install">
  <title>Gathering Information during the Installation</title>
  <para>
   During the installation, <command>supportconfig</command> is not available.
   However, you can collect log files from &yast; by using
   <command>save_y2logs</command>. This command will create a
   <filename>.tar.xz</filename> archive in the directory
   <filename>/tmp</filename>.
  </para>
  <!-- It seems that we do not have linuxrc documentation, so
  there is not much I can link to. - sknorr, 2016-07-20 -->
  <para>
   If issues appear very early during installation, you may be able to gather
   information from the log file created by
   <command>linuxrc</command>. <command>linuxrc</command> is a small command
   that runs before &yast; starts. This log file is available at
   <filename>/var/log/linuxrc.log</filename>.
  </para>
  <important>
   <title>Installation Log Files Not Available in the Installed System</title>
   <para>
    The log files available during the installation are not available in the
    installed system anymore. Properly save the installation log files while
    the installer is still running.
   </para>
  </important>
 </sect1>

 <sect1 xml:id="sec-admsupport-kernel">
  <title>Support of Kernel Modules</title>

  <para>
   An important requirement for every enterprise operating system is the level
   of support you receive for your environment. Kernel modules are the most
   relevant connector between hardware (<quote>controllers</quote>) and the
   operating system. Every kernel module in &sle; has a
   <literal>supported</literal> flag that can take three possible values:
  </para>

  <itemizedlist mark="bullet" spacing="normal">
<!-- bnc#892346: be more explicit -->
   <listitem>
    <para>
     <quote>yes</quote>, thus <literal>supported</literal>
    </para>
   </listitem>
   <listitem>
    <para>
     <quote>external</quote>, thus <literal>supported</literal>
    </para>
   </listitem>
   <listitem>
    <para>
     (empty, not set), thus <literal>unsupported</literal>
    </para>
   </listitem>
  </itemizedlist>

  <para>
   The following rules apply:
  </para>

  <itemizedlist mark="bullet" spacing="normal">
   <listitem>
    <para>
     All modules of a self-recompiled kernel are by default marked as
     unsupported.
    </para>
   </listitem>
   <listitem>
    <para>
     Kernel modules supported by &suse; partners and delivered using
     <literal>&suse; SolidDriver Program</literal> are marked
     <quote>external</quote>.
    </para>
   </listitem>
   <listitem>
    <para>
     If the <literal>supported</literal> flag is not set, loading this module
     will taint the kernel. Tainted kernels are not supported. Unsupported
     Kernel modules are included in an extra RPM package
     (<systemitem>kernel-<replaceable>FLAVOR</replaceable>-extra</systemitem>)
     that is only available for &sled; and the &sle; Workstation Extension.
     Those kernels will not be loaded by default
     (<replaceable>FLAVOR</replaceable>=<literal>default</literal>|<literal>xen</literal>|...).
     In addition, these unsupported modules are not available in the installer,
     and the
     <systemitem class="resource">kernel-<replaceable>FLAVOR</replaceable>-extra</systemitem>
     package is not part of the &sle; media.
    </para>
   </listitem>
   <listitem>
    <para>
     Kernel modules not provided under a license compatible to the license of
     the Linux kernel will also taint the kernel. For details, see
     <filename>/usr/src/linux/Documentation/sysctl/kernel.txt</filename> and
     the state of <filename>/proc/sys/kernel/tainted</filename>.
    </para>
   </listitem>
  </itemizedlist>

  <sect2 xml:id="sec-admsupport-kernel-background">
   <title>Technical Background</title>
   <para/>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      Linux kernel: The value of
      <filename>/proc/sys/kernel/unsupported</filename> defaults to
      <literal>2</literal> on &sle; &productnumber; (<literal>do not warn in
      syslog when loading unsupported modules</literal>). This default is used
      in the installer and in the installed system. See
      <filename>/usr/src/linux/Documentation/sysctl/kernel.txt</filename> for
      more information.
     </para>
    </listitem>
    <listitem>
     <para>
      <command>modprobe</command>: The <command>modprobe</command> utility for
      checking module dependencies and loading modules appropriately checks for
      the value of the <literal>supported</literal> flag. If the value is
      <quote>yes</quote> or <quote>external</quote> the module will be loaded,
      otherwise it will not. For information on how to override this behavior,
      see <xref linkend="sec-admsupport-kernel-unsupported"/>.
     </para>
     <note>
      <title>Support</title>
      <para>
       &suse; does not generally support the removal of storage modules via
       <command>modprobe -r</command>.
      </para>
     </note>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="sec-admsupport-kernel-unsupported">
   <title>Working with Unsupported Modules</title>
   <para>
    While general supportability is important, situations can occur where
    loading an unsupported module is required (for example, for testing or
    debugging purposes, or if your hardware vendor provides a hotfix).
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      To override the default, edit
      <filename>/etc/modprobe.d/10-unsupported-modules.conf</filename> and
      change the value of the variable
      <varname>allow_unsupported_modules</varname> to <literal>1</literal>. If
      an unsupported module is needed in the initrd, do not forget to run
      <command>dracut</command> <option>-f</option> to update the initrd.
     </para>
     <para>
      If you only want to try loading a module once, you can use the
      <option>--allow-unsupported-modules</option> option with
      <command>modprobe</command>. For more information, see the
      <command>modprobe</command> man page.
     </para>
    </listitem>
    <listitem>
     <para>
      During installation, unsupported modules may be added through driver
      update disks, and they will be loaded. To enforce loading of unsupported
      modules during boot and afterward, use the kernel command line option
      <option>oem-modules</option>. While installing and initializing the
      <systemitem class="resource">suse-module-tools</systemitem> package, the
      kernel flag <literal>TAINT_NO_SUPPORT</literal>
      (<filename>/proc/sys/kernel/tainted</filename>) will be evaluated. If the
      kernel is already tainted, <literal>allow_unsupported_modules</literal>
      will be enabled. This will prevent unsupported modules from failing in
      the system being installed. If no unsupported modules are present during
      installation and the other special kernel command line option
      (<option>oem-modules=1</option>) is not used, the default still is to
      disallow unsupported modules.
     </para>
    </listitem>
   </itemizedlist>
   <para>
    Remember that loading and running unsupported modules will make the kernel
    and the whole system unsupported by &suse;.
   </para>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-admsupport-moreinfo">
  <title>For More Information</title>

  <para/>

  <itemizedlist mark="bullet" spacing="normal">
   <listitem>
    <para>
     <command>man supportconfig</command>&mdash;The
     <command>supportconfig</command> man page.
    </para>
   </listitem>
   <listitem>
    <para>
     <command>man supportconfig.conf</command>&mdash;The man page of the
     supportconfig configuration file.
    </para>
   </listitem>
   <listitem>
    <para>
     <command>man scatool</command>&mdash;The <command>scatool</command> man
     page.
    </para>
   </listitem>
   <listitem>
    <para>
     <command>man scadb</command>&mdash;The <command>scadb</command> man page.
    </para>
   </listitem>
   <listitem>
    <para>
     <command>man setup-sca</command>&mdash;The <command>setup-sca</command>
     man page.
    </para>
   </listitem>
   <listitem>
    <para>
     <link xlink:href="https://mariadb.com/kb/en/"/>&mdash;The MariaDB
     documentation.
    </para>
   </listitem>
   <listitem os="sles">
    <para>
     <link xlink:href="http://httpd.apache.org/docs/"/> and
     <xref linkend="cha-apache2"/>&mdash;Documentation about the Apache Web
     server.
    </para>
   </listitem>
   <listitem os="sles">
    <para>
     <xref linkend="cha-ftp"/>&mdash;Documentation of how to set up an FTP
     server.
    </para>
   </listitem>
   <listitem>
    <para>
     <link xlink:href="https://www.suse.com/c/blog/sca-pattern-development/"/>&mdash;Instructions
     on how to create (and test) your own SCA patterns.
    </para>
   </listitem>
   <listitem>
    <para>
     <link xlink:href="https://www.suse.com/c/blog/basic-server-health-check-supportconfig/"/>&mdash;A
     Basic Server Health Check with Supportconfig.
    </para>
   </listitem>
   <listitem>
    <para>
     <link xlink:href="https://community.microfocus.com/img/gw/groupwise/w/groupwise/34308/create-your-own-supportconfig-plugin"/>&mdash;Create
     Your Own Supportconfig Plugin.
    </para>
   </listitem>
   <listitem>
    <para>
     <link xlink:href="https://www.suse.com/c/blog/creating-a-central-supportconfig-repository/"/>&mdash;Creating
     a Central Supportconfig Repository.
    </para>
    <para>
     <remark>taroth 2014-04-25: jrecord, should we still refer to the three articles above? </remark>
    </para>
   </listitem>
  </itemizedlist>
 </sect1>
</chapter>