Merge branch 'development' of https://github.com/intelkevinputnam/clear-linux-documentation into development

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

README.rst

@@ -176,7 +176,16 @@ displays a preview of the site at http://localhost:8000 on your local machine.
 
 To stop the web server simply use ``ctrl-c``.
 
+<<<<<<< HEAD
+
+### Silly header to test dev branch
+
+
+
+.. _Clear Linux\* OS documentation:  https://clearlinux.org/documentation
+=======
 .. _Clear Linux\* OS documentation:  https://docs.01.org/clearlinux/
+>>>>>>> 550b919bc013159156f80110867aa1ab7c858d29
 .. _Sphinx: http://sphinx-doc.org/
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 .. _contribution guidelines: https://docs.01.org/clearlinux/latest/collaboration/collaboration.html

source/FAQ/index.rst

@@ -198,6 +198,8 @@ Visual Studio Code
 
 |
 
+.. _licensing_restrict:
+
 Is FFmpeg available?
 ====================
 

source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css

@@ -492,6 +492,7 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a
   margin: 10px;
   border: 10px;
   background: white;
+  position: relative;
 }
 
 .column.featurecard {
@@ -499,11 +500,29 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a
   width: 300px;
 }
 
+.column.squarecard {
+  height: 320px;
+}
+
+.column.smallcard {
+  height: 150px;
+}
+
+.endlink {
+  position: absolute;
+  bottom: 10px;
+  right: 10px;
+}
+
 .column.verticalcard {
   height: 615px;
   overflow: auto;
 }
 
+.multicolumns.three {
+  max-width: 1200px;
+}
+
 /* Clear floats after the columns */
 .multicolumns:after {
   content: "";

source/about.rst

@@ -3,57 +3,93 @@
 About
 #####
 
-The |CL| delivers a secure, hardware optimized OS. Its easy updates ensure that
+|CL-ATTR| does things differently. Our software architecture provides a 
-software dependencies remain mutually compatible.
+unique and innovative platform for Linux* developers focused on
-
+performance, security, and cutting-edge computation in the cloud. 
-|CL| does this via custom infrastructure components and process innovations.
 
 .. contents::
    :local:
    :depth: 1
 
 
-For detailed information on these topics, refer to the :ref:`cl-guides` guides.
+What is |CL|?
+*************
 
+|CL| is an open source, rolling-release Linux* distribution, optimized for 
+performance and security from the cloud to the Edge.  With an emphasis on 
+customization and manageability, |CL| provides an industry blueprint on how 
+to incorporate Intel® architecture, from leveraging instruction sets to 
+optimizing kernel configurations and compiler flags, so tuning across the stack coalesces in a single, performance-driven development environment. 
 
-Release Cadence
+What |CL| isn't?
+****************
+
+|CL| is not intended to be a general-purpose Linux distribution, suitable 
+for novice end-users. While we ship common applications, our purpose isn’t 
+to make an OS for routine desktop tasks and provide immunity from all 
+security threats in all situations. Our unique focus means what we consider 
+*essential* use cases, *optional* use cases, or even *unwanted* use cases, 
+differs from other Linux distros.
+
+Target audience
 ***************
 
+Rather than making a standard Linux distribution, the |CL| team decided to
+build its own. |CL| mainly targets professionals in IT, DevOps, Cloud/
+Container deployments, and :abbr:`AI (Artifical Intelligence)`. 
+
+One advantage of developing a distro in house is that our experiments help us
+continually optimize performance and deliver security patches, several times
+per week. Yet our experiments are only valuable if our software architecture 
+gives you the freedom to innovate, too. To improve manageability, |CL| 
+employs a :ref:`stateless` design, separating user and system management.  
+
+Understanding what it takes to integrate features into our own Linux distro 
+helps us collaborate with other distro owners and submit enhancements to 
+upstream. We demonstrate the value of our distro by offering users the 
+same tools we use. For example, :ref:`mixer`, a tool unique to |CL|, allows 
+users to build custom derivatives and act as their own 
+:abbr:`(OSV) OS Vendor`. 
+
+For more details on |CL| features, refer to the :ref:`cl-guides` guides.
+
+What makes |CL| different?
+**************************
+
+Release Cadence
+===============
+
 |CL| updates are based on a rolling release that can occur daily, up to a few
-times per week. Each release has a unique version number that
+times per week. Each release has a unique version number that identifies
-identifies every component in the OS from kernel, to driver, to tool, to GUI
+every component in the OS from kernel, to driver, to tool, to GUI
-application. Most components are included in entities called *bundles*.
+application. Most components are included in entities called :ref:`bundles<bundles>`.
 
 Updates
-*******
+=======
 
-By default, |CL| automatically checks for updates, ensuring that the latest
+By default, |CL| automatically checks for updates, ensuring the latest
 performance and security fixes are installed as soon as they are available.
-:ref:`swupd-guide` is the custom tool designed to manage updates and bundles.
+|CL| stays in lockstep with upstream for current security upgrades and is 
-
+designed to rapidly deliver security mitigations to customers.
-|CL| is :ref:`stateless` to make sure that system components can be updated
+:ref:`swupd-guide` is designed to manage updates and bundles.
-without impacting user settings.
-
 
 Ease of Use
-***********
+===========
 
 |CL| makes it easier to manage a number of difficult problems.
 
 * :ref:`autoproxy` makes it possible for |CL| tools to operate in some proxy
   environments without needing to be configured.
 
-* Being :ref:`stateless` means that configuration settings are easier to manage
+* :ref:`stateless` means that configuration settings are easier to manage
   and remain untouched when system software is updated.
 
 * :ref:`swupd-guide` simplifies managing software and maintaining compatibility.
 
 Custom Derivatives
-******************
+==================
 
-The same tools used to build the |CL| are available *in* the OS. These tools can
+The same tools used to build the |CL| are available *in* the OS. These tools can be used to create a custom distribution that continues to benefit from upstream rolling releases.
-be used to create a custom distribution that continues to benefit from upstream
-rolling releases.
 
 .. figure:: /_figures/about/clear-lifecycle.png
    :scale: 75%
@@ -82,4 +118,191 @@ Administrate
 |CL| provides a :ref:`telem-guide` solution for collecting useful information
 about a deployment, as well as :ref:`debug` capabilities.
 
+Performance and security
+------------------------
+
+We apply the same strategy when it comes to performance. Our developers 
+strive to optimize performance for *essential* use cases while we ignore 
+*unwanted* or unsupported use cases.
+
+For example, while |CL| does not enable antivirus by default, we provide
+a bundle for it (`clamav`). We leave antivirus configuration to our users. 
+In addition, firewalls are less important if the OS doesn’t expose services 
+to the outside by default. In |CL|, we enforce this strategy by disabling 
+network services by default - e.g. mariadb listens on a UNIX socket, nginx 
+won’t listen at all, and other services similarly like that are restricted 
+from being accessed over the network. This strategy alone makes firewall 
+software much less urgent - there simply isn’t anything that a firewall 
+could easily block.
+
+If you want a general purpose Linux distro with little to no configuration, 
+|CL| may not be the distro enough for you. 
+
+
+Is |CL| completely Open Source?
+*******************************
+
+Wherever possible, |CL| aims to be completely open source.  Our 
+`source code`_ is available on GitHub. When considering projects for inclusion, we check that they are in active development and are well maintained. We have a very strict requirement for not accepting proprietary packages and non-open source components.  For example, many Linux distros may not be able to include certain media codecs due to  
+:ref:`licensing restrictions <licensing_restrict>`, but alternatives are available.
+
+What’s the thinking around Command line v. Desktop?
+***************************************************
+
+|CL| focuses on performance for server and cloud use-cases first because
+many design decisions associated with them are applicable to other use-cases, such as IoT and the desktop client. 
+
+While our initial focus was on the command line, we realized that many people valued the ease-of-use of a desktop environment.  We've been trying to accommodate these people as much as we can, but there are clear limits to what a desktop environment can do. This is especially true, given our desire to deliver a highly performant and secure Linux distro, one that provides unique tools for customization, and one that enables several cloud use cases. |CL| has a strong bias toward servers and what developers use, 
+rather than including "random stuff".
+
+Why create new components rather than modifying existing projects?
+******************************************************************
+
+One question that's often asked: “Why did you develop your own solution 
+instead of using <XYZ>?” (e.g. `swupd post`_).  We do evaluate existing 
+projects for inclusion in |CL|, yet there are cases where our unique 
+architecture and components would require too much customization to use 
+off-the-shelf projects.  In other situations, we may feel that using a new 
+language to develop the component would give us a performance advantage, 
+ease code development and maintenance, and grow the skills of our engineers 
+on new and upcoming programming languages.  And yes, sometimes there are 
+personal biases for and against some projects by the architects and 
+engineers.  We tend to move fast, and sometimes it’s easier to live with 
+suboptimal choices until we have the time or incentive to re-architect them 
+properly. 
+
+Which Components are used in Clear Linux?
+*****************************************
+
+.. list-table::
+   :widths: 33,33,33
+   :header-rows: 1
+
+   * - Component
+     - Enabled in OS/Bundle
+     - Optional
+
+   * - OS Installer
+     - `Clear Linux installer`_
+     - 
+
+   * - Bootloader
+     - `systemd-boot`_ (UEFI) / `syslinux`_ (Legacy)
+     - 
+
+   * - Boot Manager
+     - `Clear Linux Boot Manager`_
+     - 
+
+   * - Configuration initialization and management
+     - 
+     - `micro-config-drive`_ (minimal cloud-init), Ansible
+
+   * - Software component installer, manager, updater
+     - `swupd`_
+     - 
+
+   * - Software bundle generator - 
+     - `mixer`_ and `clr-distro-factory`_
+     - 
+
+   * - Package builder
+     - `autospec`_
+     - 
+
+   * - Software debugging
+     - 
+     - `clr-debug-info`_ 
+
+   * - Unified TLS Trust Store Management
+     - `clrtrust`_
+     - 
+
+   * - System and software telemetry
+     - 
+     - `Telemetrics`_ (disabled by default)
+
+   * - File system
+     - `EXT4`_ (default for rootfs)
+     - `VFAT`_, `EXT2 and EXT3`_, `F2FS`_
+
+   * - Disk encryption
+     - 
+     - `LUKS`_ 
+
+   * - System /Service manager  
+     - `systemd`_
+     - 
+
+   * - Display manager 
+     - `Gnome`_
+     - ``KDE``, ``i3``, ``XFCE`` ``LXQt`` (see`Clear Linux store`_)
+
+   * - Display services (Desktop installed)
+     - `X.Org`_
+     - `Wayland`_ compositor
+
+   * - Network services
+     - `NetworkManager`_ by default*, `systemd-networkd`_
+     - 
+
+   * - SSH Port scanning blocker
+     - `Tallow`_
+     - 
+
+   * - Firewall
+     - None by default
+     - iptables and `firewalld`_
+
+   * - Antivirus
+     - None by default
+     - `ClamAV®`_
+
+   * - Web browser
+     - `Lynx`_ or `links`_ for text environments, `Firefox`_ for GUI
+     - 
+
+   * - Additional Software
+     - `Supplied Bundles`_
+     - Flatpak, 3rd-party software bundles
+
+.. note::
+   
+   The |CL| OS images targeted for cloud deployments continue to use
+   ``systemd-networkd`` to manage network connections.  In earlier |CL|, 
+   ``systemd-networkd`` was used to manage Ethernet interfaces and NetworkManager was used for wireless interfaces.
+
 .. _how-to-clear: https://github.com/clearlinux/how-to-clear
+.. _Clear Linux store: https://clearlinux.org/software
+.. _source code: https://github.com/clearlinux
+.. _swupd post: https://community.clearlinux.org/t/why-does-clearlinux-use-swupd-and-not-apt-deb-rpm/
+.. _swupd: https://github.com/clearlinux/swupd-client
+.. _Clear Linux installer: https://github.com/clearlinux/clr-installer/
+.. _systemd-boot: https://www.freedesktop.org/software/systemd/man/systemd-boot.html
+.. _syslinux: https://wiki.syslinux.org/wiki/index.php?title=The_Syslinux_Project
+.. _Clear Linux Boot Manager: https://github.com/clearlinux/clr-boot-manager
+.. _mixer: https://github.com/clearlinux/mixer-tools
+.. _clr-distro-factory: https://github.com/clearlinux/clr-distro-factory
+.. _autospec: https://github.com/clearlinux/common
+.. _clr-debug-info: https://github.com/clearlinux/clr-debug-info
+.. _clrtrust: https://github.com/clearlinux/clrtrust
+.. _EXT4: https://ext4.wiki.kernel.org/index.php/Main_Page
+.. _VFAT: https://www.kernel.org/doc/html/latest/filesystems/vfat.html
+.. _EXT2 and EXT3: https://ext4.wiki.kernel.org/index.php/Main_Page
+.. _F2FS: https://www.kernel.org/doc/Documentation/filesystems/f2fs.txt
+.. _LUKS: https://gitlab.com/cryptsetup/cryptsetup/
+.. _systemd: https://www.freedesktop.org/wiki/Software/systemd/
+.. _Gnome: https://www.gnome.org/
+.. _X.Org: https://www.x.org/
+.. _Wayland: https://wayland.freedesktop.org/
+.. _NetworkManager: https://wiki.gnome.org/Projects/NetworkManager
+.. _systemd-networkd: https://www.freedesktop.org/software/systemd/man/systemd.network.html
+.. _Tallow: https://github.com/clearlinux/tallow
+.. _firewalld: https://docs.01.org/clearlinux/latest/guides/network/firewall.html#firewalld
+.. _ClamAV®: https://www.clamav.net/
+.. _Lynx: https://lynx.invisible-island.net/
+.. _links: http://links.twibright.com/
+.. _Firefox: https://www.mozilla.org/en-US/firefox/
+.. _Supplied Bundles: https://clearlinux.org/software
+.. _micro-config-drive: https://github.com/clearlinux/micro-config-drive
+.. _Telemetrics: https://github.com/clearlinux/telemetrics-backend

source/get-started/cloud-install/digitalocean.rst

@@ -147,6 +147,8 @@ Upload image
 
    See Figure 1.
 
+   .. rst-class:: dropshadow
+
    .. figure:: ../../_figures/digitalocean/01-digitalocean.png
       :scale: 100 %
       :alt: DigitalOcean - Upload custom images

source/guides/clear/index.rst

@@ -0,0 +1,79 @@
+.. _cl-guides:
+
+|CL-ATTR|
+#########
+
+.. note::
+
+   As of 22 May 2019 :file:`mixin` is no longer supported.
+
+.. container:: multicolumns three
+
+   .. container:: column smallcard featurecard
+
+      :ref:`swupd-guide`
+         Learn how to manage software and system updates in |CL|.
+
+   .. container:: column smallcard featurecard
+
+      :ref:`debug`
+         Discover how to use :command:`clr-debug-info` to leverage your
+         network to debug system software.
+
+   .. container:: column smallcard featurecard
+
+      :ref:`telem-guide`
+         Learn how you can opt-in to allow |CL| to collect data to identify
+         and fix bugs.
+
+   .. container:: column smallcard
+      
+      :ref:`autoproxy`
+          Discover how |CL| makes working behind a corporate proxy smoother.
+
+   .. container:: column smallcard
+
+      :ref:`autospec`
+         Learn about :command:`autospec` and how it used to automatically
+         include and maintain open source software in |CL|.
+
+   .. container:: column smallcard
+
+      :ref:`bundles-guide`
+         Find out what a bundle is and why it is an important part of
+         what makes |CL| secure and high performance. 
+
+   .. container:: column smallcard
+
+      :ref:`compatible-kernels`
+         Learn about all of the kernels available as installable bundles.
+
+   .. container:: column smallcard
+
+      :ref:`ister`  
+         Find out how |CL| uses this template-based installer to produce
+         images for each release.
+
+   .. container:: column smallcard
+
+      :ref:`mixer`
+         Learn how the |CL| team generates official update content and
+         releases.
+
+   .. container:: column smallcard
+
+      :ref:`security`
+         Learn how |CL| is designed to ensure the security of updates and
+         software.
+
+   .. container:: column smallcard
+
+      :ref:`stateless`
+         |CL| is stateless is designed to need little to no user
+         configuration.
+
+.. toctree::
+   :glob:
+   :hidden:
+
+   *

source/guides/index.rst

@@ -3,55 +3,75 @@
 Guides
 ######
 
-The following guides provide step-by-step instructions on using |CL|.
+.. rst-class:: colh2
 
-.. note::
+Featured Guides
 
-   As of 22 May 2019 :file:`mixin` is no longer supported.
+.. container:: multicolumns three
 
-.. _cl-guides:
+   .. container:: column smallcard
       
-Clear Linux
+      :ref:`stateless`
-===========
+         |CL| is stateless is designed to need little to no user
+         configuration. 
+
+   .. container:: column smallcard
+
+      :ref:`mixer`
+          Learn how the |CL| team generates official update content and
+          releases.
+
+   .. container:: column smallcard
+
+      :ref:`dars`
+         Learn how to use the :abbr:`DARS (Data Analytics Reference Stack)`,
+         and build your own DARS container image.
+
+   .. container:: column smallcard
+
+      :ref:`dbrs`
+         Learn about the hardware and installation requirements of
+         :abbr:`DBRS (Database Reference Stack)`, and how to use |CL|
+         to host it.
+
+   .. container:: column smallcard
+
+      :ref:`cpu-performance`
+         Learn how to modify CPU power and performance settings for your
+         usecase. 
+
+   .. container:: column smallcard
+
+      :ref:`developer-workstation`
+         Set your workstation up with all bundles needed to
+         start your |CL| development project.
+
+   .. container:: column smallcard
+
+      :ref:`vnc`
+         Learn how to use VNC to connect to a remote |CL| host.
+
+   .. container:: column smallcard
+
+      :ref:`openssh-server`
+         Learn how to set up the SSH service.
+
+   .. container:: column smallcard
+
+      :ref:`kernel-modules`
+         Learn how to correctly and reliably add kernel modules manually.
+
+   .. container:: column smallcard
+
+     :ref:`kernel-development`
+         Learn how to compile a Linux\* kernel from source using |CL|
+         development tooling.
 
 .. toctree::
-   :maxdepth: 1
+   :hidden:
-   :glob:
 
-   clear/*
+   clear/index
-
+   maintenance/index
-Maintenance
+   network/index
-===========
+   kernel/index
-
+   stacks/index
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   maintenance/*
-
-Network
-=======
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   network/*
-
-Kernel
-=======
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   kernel/*
-
-Stacks
-=======
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   stacks/*

source/guides/kernel/index.rst

@@ -0,0 +1,9 @@
+.. _kernel-guides:
+
+Kernel
+######
+
+.. toctree::
+   :glob:
+
+   *

source/guides/maintenance/index.rst

@@ -0,0 +1,9 @@
+.. _maintain-guides:
+
+Maintenance
+###########
+
+.. toctree::
+   :glob:
+
+   *

source/guides/network/index.rst

@@ -0,0 +1,9 @@
+.. _network-guides:
+
+Network
+#######
+
+.. toctree::
+   :glob:
+
+   *

source/guides/stacks/index.rst

@@ -0,0 +1,9 @@
+.. _stacks-guides:
+
+Stacks
+######
+
+.. toctree::
+   :glob:
+
+   *

source/reference/bundles/bundles.rst

@@ -15,4 +15,7 @@ Bundle list
 .. raw:: html
    :file: bundles.html.txt
 
+
+Another silly test!
+
 .. _clr-bundles repo: https://github.com/clearlinux/clr-bundles/tree/master/bundles