Micro's developers guide

DC-Micro-developers-guide

@@ -0,0 +1,14 @@
+# This file originates from the project https://github.com/openSUSE/doc-kit
+# This file can be edited downstream.
+
+MAIN="customizing-products-images.asm.xml"
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+
+PROFOS="slmicro"
+PROFCONDITION="suse-product"
+#PROFCONDITION="suse-product;beta"
+#PROFCONDITION="community-project"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"

articles/customizing-products-images.asm.xml

@@ -0,0 +1,195 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!DOCTYPE assembly
+[
+    <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<assembly version="5.2" xml:lang="en"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:trans="http://docbook.org/ns/transclusion"
+          xmlns:its="http://www.w3.org/2005/11/its"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns="http://docbook.org/ns/docbook">
+  <!-- resources section references all topic chunks used in the final article
+    -->
+  <!-- R E S O U R C E S -->
+  <!-- Glue files -->
+
+  <!-- Concept files -->
+  <resources>
+    <resource xml:id="_customizing-products-identification"
+    href="../concepts/customizing-products-identification.xml"/>
+    <resource xml:id="_customizing-products-kernel"
+    href="../concepts/customizing-products-kernel.xml"/>
+    <resource xml:id="_customizing-products-drivers"
+    href="../concepts/customizing-products-drivers.xml"/>
+    <resource xml:id="_customizing-products-images-introduction" href="../concepts/customizing-products-images-introduction.xml"/>
+
+  </resources>
+  <!-- Tasks -->
+  <resources>
+    <resource xml:id="_customizing-products-images" href="../tasks/customizing-products-images.xml"/>
+
+  </resources>
+  <!-- References -->
+
+  <!-- Legal -->
+  <resources>
+    <resource href="../common/legal.xml" xml:id="_legal">
+      <description>Legal Notice</description>
+    </resource>
+    <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
+      <description>GNU Free Documentation License</description>
+    </resource>
+  </resources>
+  <!-- S T R U C T U R E -->
+  <structure renderas="article" xml:id="customizing-images-and-product" xml:lang="en">
+    <merge>
+      <title>Customizing &productname; on Premises</title>
+
+      <!-- Create revision history to enable versioning: adjust the placeholder revhistory ID,
+           for each entry add the date of when the updated article will be published,
+           list most recent date/entry at the top -->
+      <!-- Check https://documentation.suse.com/style/current/single-html/docu_styleguide/#sec-revhistory for detailed instructions-->
+      <revhistory xml:id="rh-customizing-images-and-product">
+        <revision><date>2025-11-04</date>
+          <revdescription>
+            <!-- briefly sum up the major changes for the reader-->
+            <para>
+              Initial version
+            </para>
+          </revdescription>
+        </revision>        
+      </revhistory>
+      <!-- TODO: provide a listing of possible and validatable meta entry values. Maybe in our geekodoc repo? -->
+      <!-- add author's e-mail -->
+      <meta name="maintainer" content="[email protected]" its:translate="no"/>
+      <meta name="architecture">
+        <phrase>&x86-64;</phrase>
+        <phrase>&power;</phrase>
+      </meta>
+      <!-- enter one or more product names and version -->
+      <meta name="productname" its:translate="no">
+        <productname version="6.2" os="slmicro">&productname;</productname>
+      </meta>
+      <meta name="title" its:translate="yes">Customizing &productname; on Premises</meta>
+      <meta name="description" its:translate="yes">How to customize deployment images, kernel modules and kernel drivers
+      </meta>
+      <meta name="social-descr" its:translate="yes">Customize deployment images, kernel modules and kernel drivers</meta>
+      <!-- suitable categories has to be identical with the category selected in the docserv config -->
+      <meta name="category" its:translate="no">
+        <phrase>Systems Management</phrase>
+      </meta>
+      <!-- Determines "filter by task" filter value -->
+      <!-- either add link to list or list of tasks-->
+      <meta name="task" its:translate="no">
+        <phrase>Configuration</phrase>
+        <phrase>Installation</phrase>
+      </meta>
+      <meta name="series" its:translate="no">Products &amp; Solutions</meta>
+      <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+        <dm:bugtracker>
+          <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
+          <dm:component>Documentation</dm:component>
+          <dm:product>SUSE Linux Micro 6.2</dm:product>
+          <!--
+          if the assembly applies to multiple products/productversions, use profiling:
+          <dm:product os="sles" condition="16.0">SUSE Linux Enterprise Server 16.0</dm:product>
+          <dm:product os="sles" condition="16.1">SUSE Linux Enterprise Server 16.1</dm:product>
+          -->
+          <dm:assignee>[email protected]</dm:assignee>
+          <!-- replace with your BUGZILLA e-mail address, otherwise this does not work-->
+       </dm:bugtracker>
+        <dm:translation>yes</dm:translation>
+      </dm:docmanager>
+      <abstract>
+      <variablelist>
+        <varlistentry>
+          <term>WHAT?</term>
+          <listitem>
+            <para>
+              This article provides a comprehensive guide for customers building their own
+              solutions based on &productname;.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>WHY?</term>
+          <listitem>
+            <para>
+              You want to create a deployment image completely suited to your needs.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>EFFORT</term>
+            <listitem>
+              <para>
+                It takes about 30 minutes to read the article.
+              </para>
+            </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>GOAL</term>
+            <listitem>
+              <para>
+                You will be able to build kernel modules, drivers and images tailored to your needs.
+              </para>
+            </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>REQUIREMENTS</term>
+            <listitem>
+              <itemizedlist>
+                <listitem>
+                  <para>
+                    List the requirements to accomplish the task(s) described below.
+                  </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </abstract>
+    </merge>
+    <!-- pull in all the topic files you need -->
+    <!-- pick the appropriate type of include to match your needs -->
+    <!-- pull in a topic as is -->
+    <module resourceref="_customizing-products-images-introduction" renderas="section">
+      <merge>
+        <abstract>
+          <para/>
+        </abstract>
+      </merge>
+      </module>      
+    <!-- pull in a topic and switch the title -->
+    <module resourceref="_customizing-products-identification" renderas="section"/>
+    <module resourceref="_customizing-products-kernel" renderas="section">
+      <merge>
+        <abstract>
+          <para/>
+        </abstract>
+      </merge>
+      </module>
+      <module resourceref="_customizing-products-drivers" renderas="section">
+      <merge>
+        <abstract>
+          <para/>
+        </abstract>
+      </merge>
+      </module>
+
+    <module resourceref="_customizing-products-images" renderas="section"/>
+
+    <module resourceref="_legal"/>
+    <module resourceref="_gfdl">
+      <output renderas="appendix"/>
+    </module>
+  </structure>
+  <!-- TODO: second structure! -->
+</assembly>

concepts/customizing-products-drivers.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="customizing-images-drivers"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Creating custom drivers</title><!-- can be changed via merge in the assembly -->
+    <!--add author's email address-->
+    <meta name="maintainer" content="[email protected]" its:translate="no"/>
+    <abstract><!-- can be changed via merge in the assembly -->
+      <para>
+       The topic serves as a link to the SolidDriver Program description.
+      </para>
+    </abstract>
+  </info>
+  <para>
+Installing third-party hardware drivers in a mission-critical environment can be a source of significant concern, from ensuring compatibility to guaranteeing support. The &suse; SolidDriver Program directly addresses these challenges by creating a standardized framework for our hardware partners. This ensures that kernel drivers are delivered in a uniform, proven, and reliable manner, giving customers the confidence to integrate the latest technology into their &sle;.
+  </para>
+  <para>
+    For a detailed description of the &suse; SolidDriver Program, refer to the <link
+    xlink:href="https://drivers.suse.com/doc/SolidDriver/index.html">official documentation of the
+    program</link>.
+  </para>
+</topic>

concepts/customizing-products-identification.xml

@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="customizing-images-and-product-identification"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Identifying &suse; OEM</title><!-- can be changed via merge
+in the assembly -->
+    <!-- add author's e-mail -->
+    <meta name="maintainer" content="[email protected]" its:translate="no"/>
+    <abstract><!-- can be changed via merge in the assembly -->
+      <para>
+  Products based on &slea; support more than 7,000 software applications and
+   the widest range of hardware platforms and architectures in the industry. Partnering with &suse;
+   enables OEMs to build and deliver solutions that help customers reduce costs, manage complexity,
+   and mitigate risk. However, when &slea; family products are being bundled with a
+   system or integrated into a solution by an OEM, the system or solution needs to state the
+   OEM status to customers, users and any compliance team. An important reason for this is that the
+   terms and conditions of an OEM license agreement usually differ from a common end-user
+   license agreement (EULA).
+      </para>
+    </abstract>
+  </info>
+   <para> To mark a system as containing an OEM version of a SUSE Linux Enterprise family
+   product, follow the instructions detailed below. </para>
+
+  <section xml:id="customizing-images-and-product-identification-os-release">
+    <title>Modification of <filename>/etc/os-release</filename></title>
+     <para>The file <filename>/etc/os-release</filename> is part of the <package>*-release</package>
+    package for each product of the SUSE Linux Enterprise family. It is used to identify the
+    respective product.</para>
+
+
+     <para>If the OEM does not rebrand &slea; when integrating it into
+     the OEM solution, the file <filename>/etc/os-release</filename> shall be amended. For details
+     about the file structure, refer to the <link
+     xlink:href="https://documentation.suse.com/sles/16.0/html/SLE-os-identification">&slea;
+     OS identification</link> .</para>
+
+     <para>The definition of <filename>/etc/os-release</filename> does not cover OEM identification.
+    However, custom values can be added when correctly prefixed. We suggest OEMs to introduce:</para>
+
+<variablelist>
+  <varlistentry>
+    <term>SUSE_OEM_NAME</term>
+    <listitem>
+      <para>
+A mandatory clear identifier for the OEM solution/appliance. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>SUSE_OEM_SUPPORT_URL</term>
+    <listitem>
+      <para>
+The attribute refers to the main support page for the OEM operating system.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>SUSE_OEM_BUG_REPORT_URL</term>
+    <listitem>
+      <para>
+The attribute refers to the main bug reporting page for the OEM operating system.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>  
+
+  </section>
+
+  <section xml:id="customizing-images-and-product-identification-issues">
+    <title>Modification of <filename>/etc/issue</filename></title>
+     <para>The file <filename>/etc/issue</filename> provides a banner to a system on login.
+    As the default on &slea;, <filename>/etc/issue</filename> identifies the version,
+    architecture, kernel and currently running network configuration of the respective
+    product. An example follows.</para>
+    <screen>
+Welcome to SUSE Linux Micro 6.2  (x86_64) - Kernel \r (\l).
+
+eth0: \4{eth0} \6{eth0}
+</screen>
+<para>OEMs shall adjust <filename>/etc/issue</filename> to identify the OEM solution instead of
+     SUSE Linux Enterprise. </para>
+
+  </section>
+  <section xml:id="customizing-images-and-product-identification-rebranding">
+    <title>Completely rebranded systems</title>
+    <para>An OEM can decide to completely rebrand a SUSE
+    Linux Enterprise system. In this case, the OEM needs to create an individual
+     <package>*-release</package> package including the <filename>/etc/issue</filename> and <filename>/etc/os-release</filename> files. The
+     <package>*-release</package> package from the respective product provided by &suse; may be used
+    as a template. </para>
+
+   <para>It is important for the OEM to make sure <emphasis role="strong">no</emphasis> &suse;-originated files can be found in <filename>/etc/products.d/</filename> that would identify the
+    system as a &slea; system. Instead, the information contained in the file needs
+    to come from the OEM and explicitly identify the OEM system.</para>
+  </section>
+</topic>