mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-09-03 20:31:31 +00:00
Merge pull request #875 from intelkevinputnam/kp-docs-landing-page
Proposal for docs landing page
This commit is contained in:
Kevin Putnam
@@ -14,3 +14,6 @@ source/_build
|
||||
# ignore artifacts generated by running make py
|
||||
cloned_repo
|
||||
bundles.html.txt
|
||||
|
||||
# ignore the venv, used for running make py
|
||||
venv
|
||||
|
||||
+3
-4
@@ -4,12 +4,11 @@ python:
|
||||
- "3.6"
|
||||
|
||||
# command to install dependencies
|
||||
install:
|
||||
install:
|
||||
- pip3 install -q -r requirements.txt
|
||||
- pip3 install -q -r source/_scripts/_python/requirements.txt
|
||||
|
||||
# command to run tests
|
||||
script:
|
||||
script:
|
||||
- make py
|
||||
- make htmlall
|
||||
|
||||
@@ -52,4 +51,4 @@ deploy:
|
||||
|
||||
after_deploy:
|
||||
- wget $PUBLISH_URL
|
||||
- cat clearlinux-latest
|
||||
- cat clearlinux-latest
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
SHELL := /bin/bash
|
||||
|
||||
PY_VERSION ?= 3.6
|
||||
|
||||
all:
|
||||
make -C source html
|
||||
@@ -28,4 +31,10 @@ help:
|
||||
|
||||
clean:
|
||||
make -C source clean
|
||||
rm -rf venv
|
||||
|
||||
venv:
|
||||
virtualenv -p python$(PY_VERSION) venv;
|
||||
source venv/bin/activate; \
|
||||
pip3 install -r requirements.txt;
|
||||
|
||||
|
||||
+55
-26
@@ -10,38 +10,46 @@ documentation locally for development and testing.
|
||||
Please make yourself familiar with our `contribution guidelines`_ before
|
||||
submitting a contribution.
|
||||
|
||||
Requirements
|
||||
************
|
||||
|
||||
Make sure you have Python and Sphinx installed. We use Python 3 and
|
||||
Sphinx 1.7.5
|
||||
|
||||
The Sphinx documentation provides `instructions for installing Sphinx`_ on various
|
||||
platforms.
|
||||
|
||||
Clone the documentation repository
|
||||
**********************************
|
||||
|
||||
Once Sphinx is installed, clone the documentation repository to your
|
||||
local machine.
|
||||
Clone the documentation repository to your local machine.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ git clone https://github.com/clearlinux/clear-linux-documentation
|
||||
git clone https://github.com/clearlinux/clear-linux-documentation
|
||||
|
||||
Requirements
|
||||
************
|
||||
|
||||
Make sure you have Python 3 installed to start.
|
||||
|
||||
The Sphinx documentation provides `instructions for installing Sphinx`_
|
||||
on various platforms.
|
||||
|
||||
Use pip3 to install additional Python dependencies listed in the
|
||||
requirements.txt file found in the repository:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip3 install -r requirements.txt
|
||||
|
||||
Run the build
|
||||
*************
|
||||
|
||||
We build our documentation using Sphinx. In the source directory of your
|
||||
local clear-linux-documentation repository, build the documentation by running
|
||||
**make html**:
|
||||
local clear-linux-documentation repository, preview changes to the
|
||||
documentation by building the docs in the default language (English) by
|
||||
running ``make html``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make html
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make html
|
||||
>
|
||||
sphinx-build -b html -d _build/doctrees . _build/html
|
||||
Running Sphinx v1.7.5
|
||||
Running Sphinx v1.8.0
|
||||
making output directory...
|
||||
.
|
||||
.
|
||||
@@ -52,21 +60,42 @@ local clear-linux-documentation repository, build the documentation by running
|
||||
|
||||
Build finished. The HTML pages are in _build/html.
|
||||
|
||||
Open one of the HTML pages in a web browser to view the rendered
|
||||
documentation.
|
||||
Open one of the HTML pages found in ``source/_build/html`` in a web browser
|
||||
to view the rendered documentation.
|
||||
|
||||
If you want to build the documentation exactly as seen on the website, use
|
||||
``make py`` followed by ``make htmlall``. This builds some
|
||||
external dependenices and all supported languages.
|
||||
|
||||
Additional help
|
||||
***************
|
||||
|
||||
Cleaning up
|
||||
===========
|
||||
|
||||
When testing changes in the documentation, make sure to remove the previous
|
||||
build before building again by running **make clean**:
|
||||
build before building again by running ``make clean``:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: bash
|
||||
|
||||
$ make clean
|
||||
>
|
||||
rm -rf _build/*
|
||||
make clean
|
||||
|
||||
This will completely remove the previous build output.
|
||||
|
||||
.. _Clear Linux\* OS documentation: https://clearlinux.org/documentation
|
||||
Convenience script
|
||||
==================
|
||||
|
||||
This bash script (Linux only) includes both ``make clean`` and
|
||||
``make html``. It also starts a simple Python web server that
|
||||
displays a preview of the site at http://localhost:8000 on your local machine.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
./checkwork.sh
|
||||
|
||||
To stop the web server simply use ``ctrl-c``.
|
||||
|
||||
.. _Clear Linux\* OS documentation: https://docs.01.org/clearlinux/
|
||||
.. _Sphinx: http://sphinx-doc.org/
|
||||
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
|
||||
.. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration
|
||||
|
||||
+3
-1
@@ -3,4 +3,6 @@ sphinx==1.8
|
||||
docutils==0.14
|
||||
sphinx_rtd_theme
|
||||
sphinx-intl==2.0.0
|
||||
sphinx-sitemap==1.0.2
|
||||
sphinx-sitemap==1.0.2
|
||||
Jinja2==2.10.1
|
||||
GitPython==2.1.11
|
||||
|
||||
@@ -16,7 +16,7 @@ Why did you make another distro?
|
||||
================================
|
||||
|
||||
The |CL| team felt that performance was left on the table with Linux software.
|
||||
|CL| takes a holistic approach to improving performance across the stack. We
|
||||
|CL| takes a holistic approach to improve performance across the stack. We
|
||||
also wanted to take more modern approaches with OS updates and tooling.
|
||||
|
||||
|
|
||||
@@ -31,7 +31,7 @@ Yes, we absolutely love open source reuse and upstreaming improvements.
|
||||
How often do you update?
|
||||
========================
|
||||
|
||||
The |CL| team puts out multiple releases a week, often releasing 2 or more
|
||||
The |CL| team puts out multiple releases a week, often releasing two or more
|
||||
times a day. This rolling release approach allows |CL| to remain agile to
|
||||
upstream changes and security patches.
|
||||
|
||||
@@ -137,7 +137,7 @@ Is Microsoft\* Visual Studio Code\* available?
|
||||
|
||||
Yes. Find the CLI command for installing `VS Code`_ and other Flatpak apps in
|
||||
the `software store`_. Installing Flatpak apps is also covered in our
|
||||
:ref:`tutorial <flatpak-tutorial>`.
|
||||
:ref:`tutorial <flatpak-tutorial>`.
|
||||
|
||||
The |CL| team is working on a natively packaged version of Visual Studio Code
|
||||
for future release.
|
||||
|
||||
+2
-1
@@ -53,8 +53,9 @@ help:
|
||||
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)/*
|
||||
rm -rf reference/bundles/*.txt
|
||||
|
||||
htmlall:
|
||||
htmlall:
|
||||
$(SPHINXBUILD) -b html $(ERROROPTS) $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
$(SPHINXBUILD) -b html $(ERROROPTS) -D language='zh_CN' $(ALLSPHINXOPTS) $(BUILDDIR)/zh_CN
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 84 KiB After Width: | Height: | Size: 75 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 75 KiB After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 45 KiB After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 46 KiB After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 77 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 77 KiB After Width: | Height: | Size: 80 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 89 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 89 KiB After Width: | Height: | Size: 80 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 44 KiB After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB After Width: | Height: | Size: 94 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 94 KiB After Width: | Height: | Size: 105 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 105 KiB After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 74 KiB After Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 74 KiB After Width: | Height: | Size: 77 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 77 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 169 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 396 KiB |
@@ -0,0 +1,79 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Page Not Found</title>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
|
||||
<script async="" src="https://www.google-analytics.com/analytics.js"></script><script>(function(i,s,o,g,r,a,m){i["GoogleAnalyticsObject"]=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,"script","https://www.google-analytics.com/analytics.js","ga");ga("create", "UA-61272224-1", {"cookieDomain":"auto","allowLinker":true});ga("require", "linker");ga("linker:autoLink", [/(community\.|www\.|^)clearlinux\.org/gi], true);ga("set", "anonymizeIp", true);ga("send", "pageview");</script>
|
||||
|
||||
<style>
|
||||
|
||||
* {
|
||||
line-height: 1.2;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
html {
|
||||
color: #404040;
|
||||
display: table;
|
||||
font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
|
||||
height: 100%;
|
||||
text-align: center;
|
||||
width: 100%;
|
||||
background: #fcfcfc;
|
||||
}
|
||||
|
||||
body {
|
||||
display: table-cell;
|
||||
vertical-align: middle;
|
||||
margin: 2em auto;
|
||||
}
|
||||
|
||||
h1 {
|
||||
color: #555;
|
||||
font-size: 2em;
|
||||
font-weight: 400;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
p {
|
||||
margin: 1em auto;
|
||||
}
|
||||
|
||||
input {
|
||||
padding: .3em .5em;
|
||||
font-size: 1em;
|
||||
background-color: #fff;
|
||||
}
|
||||
|
||||
@media only screen and (max-width: 280px) {
|
||||
|
||||
body, p {
|
||||
width: 95%;
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 1.5em;
|
||||
margin: 0 0 0.3em;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<img src="https://docs.01.org/clearlinux/latest/_static/clearlinux.png" class="logo" alt="Logo">
|
||||
<h1>403 Forbidden</h1>
|
||||
<p>Sorry, looks like you don't have permission to access this page.</p>
|
||||
<p>Please go back to the <a href="https://docs.01.org/clearlinux">documentation home page</a> or try searching:</p>
|
||||
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="https://docs.01.org/clearlinux/latest/search.html" method="get">
|
||||
<input type="text" name="q" id="clear-docs-search" placeholder="Search documentation" results="0">
|
||||
<input type="hidden" name="check_keywords" value="yes">
|
||||
<input type="hidden" name="area" value="default">
|
||||
</form>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,79 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Page Not Found</title>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
|
||||
<script async="" src="https://www.google-analytics.com/analytics.js"></script><script>(function(i,s,o,g,r,a,m){i["GoogleAnalyticsObject"]=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,"script","https://www.google-analytics.com/analytics.js","ga");ga("create", "UA-61272224-1", {"cookieDomain":"auto","allowLinker":true});ga("require", "linker");ga("linker:autoLink", [/(community\.|www\.|^)clearlinux\.org/gi], true);ga("set", "anonymizeIp", true);ga("send", "pageview");</script>
|
||||
|
||||
<style>
|
||||
|
||||
* {
|
||||
line-height: 1.2;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
html {
|
||||
color: #404040;
|
||||
display: table;
|
||||
font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
|
||||
height: 100%;
|
||||
text-align: center;
|
||||
width: 100%;
|
||||
background: #fcfcfc;
|
||||
}
|
||||
|
||||
body {
|
||||
display: table-cell;
|
||||
vertical-align: middle;
|
||||
margin: 2em auto;
|
||||
}
|
||||
|
||||
h1 {
|
||||
color: #555;
|
||||
font-size: 2em;
|
||||
font-weight: 400;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
p {
|
||||
margin: 1em auto;
|
||||
}
|
||||
|
||||
input {
|
||||
padding: .3em .5em;
|
||||
font-size: 1em;
|
||||
background-color: #fff;
|
||||
}
|
||||
|
||||
@media only screen and (max-width: 280px) {
|
||||
|
||||
body, p {
|
||||
width: 95%;
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 1.5em;
|
||||
margin: 0 0 0.3em;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<img src="https://docs.01.org/clearlinux/latest/_static/clearlinux.png" class="logo" alt="Logo">
|
||||
<h1>404 Not Found</h1>
|
||||
<p>Sorry, we didn't find the page you're looking for.</p>
|
||||
<p>Please go back to the <a href="https://docs.01.org/clearlinux">documentation home page</a> or try searching:</p>
|
||||
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="https://docs.01.org/clearlinux/latest/search.html" method="get">
|
||||
<input type="text" name="q" id="clear-docs-search" placeholder="Search documentation" results="0">
|
||||
<input type="hidden" name="check_keywords" value="yes">
|
||||
<input type="hidden" name="area" value="default">
|
||||
</form>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,9 +1,6 @@
|
||||
|
||||
py:
|
||||
python bundle_lister.py
|
||||
python3 bundle_lister.py
|
||||
cp bundles.html.txt ../../reference/bundles
|
||||
rm -rf bundle_lister/cloned_repo/*
|
||||
rm -rf ./cloned_repo/*
|
||||
rm bundles.html.txt
|
||||
@echo "Python script finished successfully!"
|
||||
|
||||
|
||||
|
||||
@@ -1,2 +0,0 @@
|
||||
Jinja2==2.10.1
|
||||
GitPython==2.1.11
|
||||
@@ -119,6 +119,8 @@ th,td {
|
||||
padding-left: 0 !important;
|
||||
}
|
||||
|
||||
/*Begin support for collapsbile sections*/
|
||||
|
||||
.clps1 {
|
||||
font-size: 175%;
|
||||
}
|
||||
@@ -176,6 +178,26 @@ th,td {
|
||||
transition: max-height 0.2s ease-out;
|
||||
}
|
||||
|
||||
/*Fix for permalinks to collapsible sections*/
|
||||
|
||||
button a.headerlink {
|
||||
visibility: hidden;
|
||||
}
|
||||
|
||||
button a.headerlink:after {
|
||||
content: "\f0c1";
|
||||
font-size: 14px;
|
||||
font-family: FontAwesome;
|
||||
font-weight: normal;
|
||||
}
|
||||
|
||||
button:hover a.headerlink:after {
|
||||
visibility: visible;
|
||||
}
|
||||
|
||||
/*End support for collapsbile sections*/
|
||||
|
||||
/*Begin support for custom Clear Linux header*/
|
||||
#header {
|
||||
width: 100%;
|
||||
display: block;
|
||||
@@ -278,6 +300,8 @@ th,td {
|
||||
line-height: 100px;
|
||||
}
|
||||
|
||||
/*End support for custom Clear Linux header*/
|
||||
|
||||
/*Adds a bit of spacing after the last paragraph in a bulleted list*/
|
||||
.wy-plain-list-disc li p:last-child, .rst-content .section ul li p:last-child, .rst-content .toctree-wrapper ul li p:last-child, article ul li p:last-child {
|
||||
margin-bottom: 10px;
|
||||
@@ -291,7 +315,7 @@ div#trademarks {
|
||||
color: gray;
|
||||
}
|
||||
|
||||
|
||||
/*Adds magnifying glass to search box*/
|
||||
#clear-docs-search {
|
||||
background: url(./mag-glass.png) left no-repeat;
|
||||
background-size: 15px 15px;
|
||||
@@ -312,3 +336,178 @@ div#trademarks {
|
||||
.pending-delete-status {
|
||||
color:#ce2029;
|
||||
}
|
||||
|
||||
/*Begin support for code blocks with $ signs that aren't copied with content*/
|
||||
|
||||
.bash-dollar:before {
|
||||
content: '$ ';
|
||||
}
|
||||
|
||||
/*End support for code blocks with $ signs that aren't copied with content*/
|
||||
|
||||
/*Begin support for labeled code-blocks - need to add an entry for every type of code-block that needs to be labeled*/
|
||||
|
||||
div.highlight-powershell .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " PowerShell ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-python .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " Python ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-console .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " Console ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-rst, div.highlight-rest .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " reStructuredText ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-yaml .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " yaml ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-bash .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " bash ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-diff .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " Diff ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-c .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " c ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-json .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " json ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-spec .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " spec ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-perl .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " Perl ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-php .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " php ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.highlight-xml .highlight:before{
|
||||
background: #909090;
|
||||
color: white;
|
||||
content: " xml ";
|
||||
font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
|
||||
font-size: 14px;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
div.linenodiv:before { /*add extra new line to make sure code and line numbers align*/
|
||||
content: '\00000a';
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
/*End support for labeled code-blocks*/
|
||||
|
||||
/*Begin support for multi-column sections*/
|
||||
|
||||
.column {
|
||||
float: left;
|
||||
width: 350px;
|
||||
padding: 10px;
|
||||
margin: 10px;
|
||||
border: 10px;
|
||||
background: white;
|
||||
}
|
||||
|
||||
.column.featurecard {
|
||||
background: #CCE9F5;
|
||||
}
|
||||
|
||||
.column.verticalcard {
|
||||
height: 615px;
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
/* Clear floats after the columns */
|
||||
.multicolumns:after {
|
||||
content: "";
|
||||
display: table;
|
||||
clear: both;
|
||||
}
|
||||
|
||||
.colh2 {
|
||||
font-size: 150%;
|
||||
font-weight: 700;
|
||||
font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;
|
||||
}
|
||||
|
||||
.video.docutils.container {
|
||||
margin: 10px;
|
||||
width:720px;
|
||||
height:405px;
|
||||
}
|
||||
|
||||
/*End support for multi-column sections*/
|
||||
|
||||
@@ -1,21 +1,34 @@
|
||||
var i;
|
||||
var contents = document.getElementsByClassName("content-collapse section");
|
||||
|
||||
var bashDollarDivs = document.getElementsByClassName("bash-dollars highlight-bash");
|
||||
|
||||
for (i = 0; i< bashDollarDivs.length; i++) {
|
||||
_pre = bashDollarDivs[i].querySelectorAll("pre");
|
||||
for (j = 0; j < _pre.length; j++) {
|
||||
console.log(_pre[j]);
|
||||
_pre[j].innerHTML="<span class='bash-dollar'>"+(_pre[j].textContent.split("\n").filter(Boolean).join("</span>\n<span class='bash-dollar'>"))+"</span>";
|
||||
}
|
||||
}
|
||||
|
||||
for (i = 0; i < contents.length; i++) {
|
||||
|
||||
//Make sure the "content-collapse section" class is occurring in <div>
|
||||
if (contents[i].tagName.toLowerCase() == 'div') {
|
||||
var element = contents[i].children[0];
|
||||
var element_type = element.tagName.toLowerCase();
|
||||
var span_id;
|
||||
var spanElement;
|
||||
var btn_id;
|
||||
var divElement;
|
||||
|
||||
//if the next element is a span grab the id and skip to the header
|
||||
divElement = contents[i];
|
||||
btn_id = contents[i].id;
|
||||
|
||||
//if the next element is a span skip to the header
|
||||
if (element_type == 'span') {
|
||||
span_id = element.id;
|
||||
element.id = "";
|
||||
element = contents[i].children[1];
|
||||
element_type = element.tagName.toLowerCase();
|
||||
} else {
|
||||
divElement.id = "";
|
||||
}
|
||||
|
||||
var btn = document.createElement("BUTTON");
|
||||
@@ -28,7 +41,7 @@ for (i = 0; i < contents.length; i++) {
|
||||
btn.className += " " + newClass;
|
||||
btn.innerHTML = element.innerHTML;
|
||||
btn.className += " collapsible";
|
||||
btn.id = span_id;
|
||||
btn.id = btn_id;
|
||||
btn.addEventListener("click", function() {
|
||||
this.classList.toggle("active");
|
||||
var content = this.nextElementSibling;
|
||||
@@ -42,9 +55,6 @@ for (i = 0; i < contents.length; i++) {
|
||||
//Add the button to the page and remove the header
|
||||
contents[i].parentNode.insertBefore(btn, contents[i]);
|
||||
contents[i].removeChild(element);
|
||||
}else{
|
||||
//reset span id if it isn't followed by Hx element
|
||||
spanElement.id = span_id;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
.. _collaboration:
|
||||
|
||||
Contribute
|
||||
##########
|
||||
|
||||
There are multiple ways to help improve our documentation:
|
||||
|
||||
* `Contribute via GitHub`_: Submit pull requests in the GitHub\* documentation
|
||||
repository.
|
||||
* `Log an issue`_: Enter an issue in the documentation repository for
|
||||
minor issues such as typos.
|
||||
* `Make a suggestion`_: Send your documentation suggestion to the mailing list.
|
||||
* Test documentation: Step through our guides and tutorials to verify the
|
||||
instructions. `Log an issue`_ or `submit a pull request`_ with your findings.
|
||||
|
||||
All contributions must follow our `code of conduct`_.
|
||||
|
||||
Contribute via GitHub
|
||||
*********************
|
||||
|
||||
Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_.
|
||||
Here are the basic steps for contributing:
|
||||
|
||||
#. Clone the `documentation repository`_.
|
||||
|
||||
#. Create your own fork of the repository.
|
||||
|
||||
#. Create a branch for your contribution.
|
||||
|
||||
#. Add your commits.
|
||||
|
||||
#. Open a pull request.
|
||||
|
||||
#. Discuss, review, and update your contributions.
|
||||
|
||||
#. Once the maintainer approves, your contribution is merged and published as
|
||||
part of the documentation.
|
||||
|
||||
|
||||
Contribution guidelines
|
||||
***********************
|
||||
|
||||
The |CL| documentation is written using reStructuredText. Use our guidelines
|
||||
and best practices to write consistent, readable documentation.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Writing guide <writing-guide>
|
||||
Structure and formatting guide <structure-formatting>
|
||||
|
||||
.. _references:
|
||||
|
||||
References
|
||||
**********
|
||||
|
||||
We use the following references for grammar, style, and formatting:
|
||||
|
||||
* `Microsoft Writing Style Guide`_
|
||||
* `Merriam-Webster Dictionary`_
|
||||
* The Chicago Manual of Style (15th edition), The University of Chicago Press
|
||||
* Microsoft Press Computer Dictionary, Microsoft Press
|
||||
* Read Me First!, Oracle Technical Publications
|
||||
|
||||
|
||||
.. _`code of conduct`: https://clearlinux.org/community/code-of-conduct
|
||||
.. _Make a suggestion: https://lists.clearlinux.org/postorius/lists/dev.lists.clearlinux.org/
|
||||
.. _GitHub flow: https://guides.github.com/introduction/flow/
|
||||
.. _Log an issue: https://github.com/clearlinux/clear-linux-documentation/issues
|
||||
.. _Contribute via GitHub: https://github.com/clearlinux/clear-linux-documentation
|
||||
.. _submit a pull request: https://github.com/clearlinux/clear-linux-documentation
|
||||
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
|
||||
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
|
||||
.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/
|
||||
+4
-2
@@ -132,6 +132,7 @@ html_theme_options = {
|
||||
'navigation_depth': 4,
|
||||
'display_version': False,
|
||||
'collapse_navigation': False,
|
||||
'prev_next_buttons_location': 'None',
|
||||
'sticky_navigation': True
|
||||
}
|
||||
|
||||
@@ -178,7 +179,7 @@ html_favicon = '_images/favicon.ico'
|
||||
# Add any extra paths that contain custom files (such as robots.txt or
|
||||
# .htaccess) here, relative to this directory. These files are copied
|
||||
# directly to the root of the documentation.
|
||||
#html_extra_path = []
|
||||
html_extra_path = ['_html_extra']
|
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||
# using the given strftime format.
|
||||
@@ -330,4 +331,5 @@ texinfo_documents = [
|
||||
locale_dirs = ['../locale/'] # path for lang-specific po files.
|
||||
gettext_compact = False # optional.
|
||||
|
||||
html_baseurl = 'https://docs.01.org/clearlinux/'
|
||||
html_baseurl = 'https://docs.01.org/clearlinux/'
|
||||
|
||||
|
||||
@@ -31,13 +31,8 @@ Preliminary steps
|
||||
|
||||
<release-number> is the latest |CL| auto-numbered release.
|
||||
|
||||
#. Verify and decompress the file per your OS.
|
||||
|
||||
* :ref:`download-verify-decompress`
|
||||
|
||||
#. Follow your OS instructions to create a bootable USB drive.
|
||||
|
||||
* :ref:`bootable-usb`
|
||||
#. Follow your OS instructions to
|
||||
:ref:`create a bootable usb drive <bootable-usb>`.
|
||||
|
||||
.. _install-on-target-start:
|
||||
|
||||
@@ -111,20 +106,6 @@ Launch the |CL| installer
|
||||
|
||||
#. Select :guilabel:`Next`.
|
||||
|
||||
Checking prerequisites
|
||||
======================
|
||||
|
||||
The installer automatically launches :guilabel:`Checking Prerequisites`,
|
||||
which checks your target system for compatibility and network connectivity.
|
||||
|
||||
After the installer shows `Prerequisites passed`, select :guilabel:`Next` to
|
||||
proceed with installation.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-04.png
|
||||
:scale: 100%
|
||||
:alt: Checking Prerequisites
|
||||
|
||||
Figure 4: Checking Prerequisites
|
||||
|
||||
Network Proxy (optional)
|
||||
------------------------
|
||||
@@ -165,16 +146,16 @@ To fulfill minimum installation requirements, complete the
|
||||
|CL| Desktop Installer
|
||||
**********************
|
||||
|
||||
The |CL| Desktop Installer Main Menu appears as shown in Figure 5. To meet
|
||||
The |CL| Desktop Installer Main Menu appears as shown in Figure 4. To meet
|
||||
the minimum requirements, enter values in all submenus for the
|
||||
:guilabel:`Required options`. After you complete them, your selections appear
|
||||
below submenus and a check mark appears at right.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-05.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-04.png
|
||||
:scale: 100%
|
||||
:alt: Clear Linux OS Desktop Installer - Main Menu
|
||||
|
||||
Figure 5: Clear Linux OS Desktop Installer - Main Menu
|
||||
Figure 4: Clear Linux OS Desktop Installer - Main Menu
|
||||
|
||||
Navigation
|
||||
**********
|
||||
@@ -203,11 +184,11 @@ Select Time Zone
|
||||
|
||||
#. Select :guilabel:`Confirm`.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-06.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-05.png
|
||||
:scale: 100%
|
||||
:alt: Select System Timezone
|
||||
|
||||
Figure 6: Select System Time Zone
|
||||
Figure 5: Select System Time Zone
|
||||
|
||||
Select Keyboard
|
||||
===============
|
||||
@@ -219,11 +200,11 @@ Select Keyboard
|
||||
|
||||
#. Select :guilabel:`Confirm`.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-07.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-06.png
|
||||
:scale: 100%
|
||||
:alt: Select Keyboard menu
|
||||
|
||||
Figure 7: Select Keyboard menu
|
||||
Figure 6: Select Keyboard menu
|
||||
|
||||
Select Installation Media
|
||||
=========================
|
||||
@@ -233,11 +214,11 @@ Select Installation Media
|
||||
#. Choose an installation method: `Safe Installation`_ or
|
||||
`Destructive Installation`_.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-08.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-07.png
|
||||
:scale: 100%
|
||||
:alt: Select Installation Media
|
||||
|
||||
Figure 8: Select Installation Media
|
||||
Figure 7: Select Installation Media
|
||||
|
||||
Safe Installation
|
||||
-----------------
|
||||
@@ -268,21 +249,21 @@ For greater security, disk encryption is supported using LUKS. Encryption is
|
||||
optional.
|
||||
|
||||
#. To encrypt the root partition, select :guilabel:`Enable Encryption`,
|
||||
as shown in Figure 9.
|
||||
as shown in Figure 8.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-09.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-08.png
|
||||
:scale: 100%
|
||||
:alt: Enable Encryption
|
||||
|
||||
Figure 9: Enable Encryption
|
||||
Figure 8: Enable Encryption
|
||||
|
||||
#. When :guilabel:`Encryption Passphrase` appears, enter a passphrase.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-10.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-09.png
|
||||
:scale: 100%
|
||||
:alt: Encryption Passphrase
|
||||
|
||||
Figure 10: Encryption Passphrase
|
||||
Figure 9: Encryption Passphrase
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -310,22 +291,22 @@ Our example uses the `Default partition schema`_. The space you allocate for
|
||||
|
||||
#. Select :guilabel:`Partition Media`, shown in Figure 11.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-11.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-10.png
|
||||
:scale: 100%
|
||||
:alt: Advanced Installation
|
||||
|
||||
Figure 11: Advanced Installation
|
||||
Figure 10: Advanced Installation
|
||||
|
||||
boot partition
|
||||
--------------
|
||||
|
||||
#. Select the available target media shown as `unallocated`.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-12.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-11.png
|
||||
:scale: 100%
|
||||
:alt: Advanced Disk Partitioning
|
||||
|
||||
Figure 12: Advanced Disk Partitioning
|
||||
Figure 11: Advanced Disk Partitioning
|
||||
|
||||
#. Choose :menuselection:`Device --> Create Partition Table`.
|
||||
|
||||
@@ -341,18 +322,18 @@ boot partition
|
||||
The `/boot` partition must be `VFAT(FAT32)`.
|
||||
|
||||
#. In :guilabel:`Create new Partition`, complete the following fields to
|
||||
match Figure 13. Don't change other default values.
|
||||
match Figure 12. Don't change other default values.
|
||||
|
||||
* :guilabel:`New size:` 150
|
||||
* :guilabel:`Partition name:` CLR_BOOT
|
||||
* :guilabel:`File system:` fat32
|
||||
* :guilabel:`Label:` boot
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-13.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-12.png
|
||||
:scale: 100%
|
||||
:alt: boot partition
|
||||
|
||||
Figure 13: boot partition
|
||||
Figure 12: boot partition
|
||||
|
||||
#. Select :guilabel:`Add`.
|
||||
|
||||
@@ -363,18 +344,18 @@ swap partition
|
||||
:menuselection:`Partition --> New`.
|
||||
|
||||
#. In :guilabel:`Create new Partition`, complete the following fields to
|
||||
match Figure 14. Don't change other default values.
|
||||
match Figure 13. Don't change other default values.
|
||||
|
||||
* :guilabel:`New size:` 256
|
||||
* :guilabel:`Partition name:` CLR_SWAP
|
||||
* :guilabel:`File system:` linux-swap
|
||||
* :guilabel:`Label:` swap
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-14.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-13.png
|
||||
:scale: 100%
|
||||
:alt: swap partition
|
||||
|
||||
Figure 14: swap partition
|
||||
Figure 13: swap partition
|
||||
|
||||
#. Select :guilabel:`Add`.
|
||||
|
||||
@@ -385,7 +366,7 @@ root partition
|
||||
:menuselection:`Partition --> New`.
|
||||
|
||||
#. In :guilabel:`Create new Partition`, complete the following fields to
|
||||
match Figure 15. Don't change other default values.
|
||||
match Figure 14. Don't change other default values.
|
||||
|
||||
#. In :guilabel:`New size`, enter the desired size, or leave as is
|
||||
to accept the *default: remaining size*.
|
||||
@@ -395,20 +376,20 @@ root partition
|
||||
* :guilabel:`File system:` ext[234] or XFS
|
||||
* :guilabel:`Label:` root
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-15.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-14.png
|
||||
:scale: 100%
|
||||
:alt: root partition
|
||||
|
||||
Figure 15: root partition
|
||||
Figure 14: root partition
|
||||
|
||||
#. After all partitions are defined, verify your partition
|
||||
configuration is similar to Figure 16.
|
||||
configuration is similar to Figure 15.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-16.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-15.png
|
||||
:scale: 100%
|
||||
:alt: Final partition configuration
|
||||
|
||||
Figure 16: Final partition configuration
|
||||
Figure 15: Final partition configuration
|
||||
|
||||
#. Select :menuselection:`Edit --> Apply All Operations`.
|
||||
|
||||
@@ -431,11 +412,11 @@ Manage User
|
||||
|
||||
#. In :guilabel:`User Name`, enter a user name.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-17.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-16.png
|
||||
:scale: 100%
|
||||
:alt: Manage User
|
||||
|
||||
Figure 17: Manage User
|
||||
Figure 16: Manage User
|
||||
|
||||
#. In :guilabel:`Login`, create a login name. It must start with a letter
|
||||
and can use numbers, hyphens, and underscores. Maximum length is 31
|
||||
@@ -485,11 +466,11 @@ team for improvements.
|
||||
|
||||
#. Select :kbd:`Yes`.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-18.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-17.png
|
||||
:scale: 100%
|
||||
:alt: Enable Telemetry
|
||||
|
||||
Figure 18: Enable Telemetry
|
||||
Figure 17: Enable Telemetry
|
||||
|
||||
#. If you don't wish to participate, select :kbd:`No`.
|
||||
|
||||
@@ -505,28 +486,31 @@ after reboot.
|
||||
|
||||
You can always add more bundles later with :ref:`swupd-guide`.
|
||||
|
||||
Bundle Selection
|
||||
================
|
||||
Select Additional Bundles
|
||||
=========================
|
||||
|
||||
#. On the Advanced menu, select :guilabel:`Bundle Selection`
|
||||
This option is only available with a valid network connection.
|
||||
Bundle selection is disabled if no network connection exists.
|
||||
|
||||
#. On the Advanced menu, select :guilabel:`Select Additional Bundles`.
|
||||
|
||||
#. Select your desired bundles.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-19.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-18.png
|
||||
:scale: 100%
|
||||
:alt: Bundle Selection
|
||||
|
||||
Figure 19: Bundle Selection
|
||||
Figure 18: Bundle Selection
|
||||
|
||||
#. Select :kbd:`Confirm`.
|
||||
|
||||
#. View the bundles that you selected.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-20.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-19.png
|
||||
:scale: 100%
|
||||
:alt: Bundle Selections - Advanced Options
|
||||
:alt: Select Additional Bundles
|
||||
|
||||
Figure 20: Bundle Selections - Advanced Options
|
||||
Figure 19: Select Additional Bundles
|
||||
|
||||
Optional: Skip to `Finish installation`_.
|
||||
|
||||
@@ -537,11 +521,11 @@ Assign Hostname
|
||||
|
||||
#. In :guilabel:`Hostname`, enter the hostname only (excluding the domain).
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-21.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-20.png
|
||||
:scale: 100%
|
||||
:alt: Assign Hostname
|
||||
|
||||
Figure 21: Assign Hostname
|
||||
Figure 20: Assign Hostname
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -559,11 +543,11 @@ Kernel Configuration
|
||||
#. In :guilabel:`Kernel Configuration`, navigate to select your desired
|
||||
kernel. :guilabel:`Native` is selected by default.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-22.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-21.png
|
||||
:scale: 100%
|
||||
:alt: Kernel Configuration
|
||||
|
||||
Figure 22: Kernel Configuration
|
||||
Figure 21: Kernel Configuration
|
||||
|
||||
#. To add arguments, enter the argument in :guilabel:`Add Extra Arguments`.
|
||||
|
||||
@@ -582,11 +566,11 @@ Software Updater Configuration
|
||||
#. :guilabel:`Enable Auto Updates` is selected by default. If you **do not**
|
||||
wish to enable automatic software updates, uncheck the box.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-23.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-22.png
|
||||
:scale: 100%
|
||||
:alt: Software Updater Configuration
|
||||
|
||||
Figure 23: Software Updater Configuration
|
||||
Figure 22: Software Updater Configuration
|
||||
|
||||
#. Select :kbd:`Confirm`.
|
||||
|
||||
@@ -596,11 +580,11 @@ Finish installation
|
||||
#. When you are satisfied with your installation configuration, select
|
||||
:guilabel:`Install`.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-24.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-23.png
|
||||
:scale: 100%
|
||||
:alt: Assign Hostname
|
||||
|
||||
Figure 24: Finish installation
|
||||
Figure 23: Finish installation
|
||||
|
||||
.. note:
|
||||
|
||||
@@ -609,13 +593,13 @@ Finish installation
|
||||
|
||||
#. If you do not enter a selection for all :guilabel:`Required Options`,
|
||||
the :guilabel:`Install` button remains disabled, as shown
|
||||
in Figure 25. Return to `Required Options`_ and make selections.
|
||||
in Figure 24. Return to `Required Options`_ and make selections.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-25.png
|
||||
.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-24.png
|
||||
:scale: 100%
|
||||
:alt: Required Options - Incomplete
|
||||
|
||||
Figure 25: Required Options - Incomplete
|
||||
Figure 24: Required Options - Incomplete
|
||||
|
||||
#. After installation is complete, select :guilabel:`Exit`.
|
||||
|
||||
|
||||
@@ -22,16 +22,17 @@ installation:
|
||||
Download the latest |CL| live server image
|
||||
******************************************
|
||||
|
||||
Get the latest |CL| installer image from the `Downloads`_ page. Look for the
|
||||
:file:`clear-[version number]-live-server.iso` file.
|
||||
#. Visit our `Downloads`_ page.
|
||||
|
||||
#. Verify and decompress the file per your OS.
|
||||
#. Download the file :file:`clear-<release number>-live-server.iso`,
|
||||
also called the |CL| Server.
|
||||
|
||||
* :ref:`download-verify-decompress`
|
||||
.. note::
|
||||
|
||||
#. Follow your OS instructions to create a bootable USB drive.
|
||||
<release-number> is the latest |CL| auto-numbered release.
|
||||
|
||||
* :ref:`bootable-usb`
|
||||
#. Follow your OS instructions to
|
||||
:ref:`create a bootable usb drive <bootable-usb>`.
|
||||
|
||||
Install |CL| on your target system
|
||||
**********************************
|
||||
@@ -356,11 +357,16 @@ root partition
|
||||
|
||||
.. note::
|
||||
|
||||
You may also append the following labels:
|
||||
You may also append `_F` to the partition name to force the formatting.
|
||||
|
||||
* `CLR_ROOT_E`: Adds encryption
|
||||
* `CLR_ROOT_F`: Formats the partition prior to use
|
||||
* `CLR_ROOT_E_F`: Adds encryption and formats the partition
|
||||
* `CLR_ROOT_F`: Force the formatting of the root partition prior to
|
||||
use.
|
||||
|
||||
* `CLR_F_SWAP`: Force the formatting of the swap partition prior to
|
||||
use; helpful when re-using a partition for swap which was previously formatted for a file system.
|
||||
|
||||
* `CLR_F_MNT_/data`: Force the formatting of the extra data
|
||||
partition prior to use
|
||||
|
||||
#. Press :kbd:`Enter`.
|
||||
|
||||
@@ -401,8 +407,11 @@ Additional partitions (optional)
|
||||
|
||||
Figure 15: CLR_MNT
|
||||
|
||||
.. note::
|
||||
|
||||
If formatting is desired, the `_F` **must precede** `_MNT`.
|
||||
|
||||
#. Alternatively, you may create `CLR_MNT_/srv` or other partitions.
|
||||
Use of the `_E` or `_F` **must** precede `_MNT`.
|
||||
|
||||
Write configuration to disk
|
||||
---------------------------
|
||||
@@ -597,6 +606,9 @@ Test Network Settings
|
||||
To manually assure network connectivity before installing |CL|,
|
||||
select :guilabel:`Test Network Settings` and select :guilabel:`Enter`.
|
||||
|
||||
.. note::
|
||||
If using the :command:`off-line installer`, this option is not available.
|
||||
|
||||
A progress bar appears as shown in Figure 22.
|
||||
|
||||
.. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-22.png
|
||||
@@ -612,10 +624,13 @@ A progress bar appears as shown in Figure 22.
|
||||
|
||||
Optional: Skip to `Finish installation`_.
|
||||
|
||||
Bundle Selection
|
||||
================
|
||||
Select Additional Bundles
|
||||
=========================
|
||||
|
||||
#. On the Advanced menu, select :guilabel:`Bundle Selection`
|
||||
This option is only available with a valid network connection.
|
||||
Bundle selection is disabled if no network connection exists.
|
||||
|
||||
#. On the Advanced menu, select :guilabel:`Select Additional Bundles`.
|
||||
|
||||
#. Navigate to the desired bundle using :kbd:`Tab` or :kbd:`Up/Down` arrows.
|
||||
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
Create a bootable USB drive
|
||||
###########################
|
||||
|
||||
Follow the instructions applicable to your system to create a bootable |CL-ATTR|
|
||||
USB drive:
|
||||
Follow the instructions applicable to your system to create a bootable
|
||||
|CL-ATTR| USB drive:
|
||||
|
||||
* :ref:`bootable-usb-linux`
|
||||
* :ref:`bootable-usb-mac`
|
||||
@@ -13,34 +13,29 @@ USB drive:
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
* Use an **8GB** or larger USB drive.
|
||||
* Download the |CL| live boot image or interactive installer image from the
|
||||
`Downloads`_ page.
|
||||
* Download the |CL| Desktop or Server image from the `Downloads`_ page
|
||||
* Recommended minimum **4GB** USB drive or larger
|
||||
|
||||
.. _bootable-usb-linux:
|
||||
|
||||
Create a bootable USB drive on Linux\*
|
||||
**************************************
|
||||
|
||||
Make sure you have completed all `Prerequisites`_.
|
||||
* Make sure you completed all `Prerequisites`_.
|
||||
|
||||
Before burning the image onto your USB drive, :ref:`verify-linux` on Linux.
|
||||
* :ref:`verify-linux` on Linux.
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
Burning an image formats the USB drive, and will destroy all pre-existing
|
||||
Burning an image formats the USB drive and destroys all pre-existing
|
||||
content. Back up your data before proceeding.
|
||||
|
||||
#. Open a terminal emulator and get root privilege.
|
||||
#. Open a terminal window.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo -s
|
||||
|
||||
#. Go to the directory with the decompressed image.
|
||||
#. Change directory to where the image resides.
|
||||
|
||||
#. Plug in the USB drive.
|
||||
|
||||
@@ -48,7 +43,7 @@ Burn the |CL| image onto a USB drive
|
||||
drives attached to the system, including the primary hard disk. In the
|
||||
example output below, there are 4 drives
|
||||
(`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where
|
||||
`/dev/sda` is primary drive. The remaining are three USB drives. The output
|
||||
`/dev/sda` is the primary drive. The remaining are three USB drives. The output
|
||||
also shows the mounted partitions (under the `MOUNTPOINT` column) for each
|
||||
drive.
|
||||
|
||||
@@ -59,6 +54,7 @@ Burn the |CL| image onto a USB drive
|
||||
Example output:
|
||||
|
||||
.. code-block:: console
|
||||
:emphasize-lines: 1-5
|
||||
|
||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
|
||||
sdd 8:48 1 15G 0 disk
|
||||
@@ -79,22 +75,24 @@ Burn the |CL| image onto a USB drive
|
||||
├─sda8 8:8 0 30G 0 part /
|
||||
└─sda6 8:6 0 7.9G 0 part [SWAP]
|
||||
|
||||
#. You must unmount a USB drive before burning an image onto it. Note that
|
||||
some Linux distros automatically mount a USB drive when it is plugged in.
|
||||
Unmount a USB drive with the :command:`umount` command followed by the device
|
||||
identifier/partition. For example:
|
||||
.. note::
|
||||
|
||||
Some Linux distros may automatically mount a USB drive when it is plugged in.
|
||||
|
||||
#. If the USB drive you want to use is mounted, it must be umounted before
|
||||
burning an image onto it. Use the :command:`umount` command followed by
|
||||
the device identifier/partition. For example, to unmount all /dev/sdd
|
||||
partitions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
umount /dev/sdd2
|
||||
umount /dev/sdd3
|
||||
sudo umount /dev/sdd*
|
||||
|
||||
#. Burn the image onto the USB drive. The example below burns an uncompressed
|
||||
image onto `<your USB device>`:
|
||||
#. Burn the image onto the USB drive. The example below burns an image onto `<your USB device>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
dd if=./clear-[version number]-[image type] of=<your USB device> oflag=sync bs=4M status=progress
|
||||
sudo dd if=./clear-[version number]-live-[desktop | server].iso of=<your USB device> oflag=sync bs=4M status=progress
|
||||
|
||||
.. caution::
|
||||
|
||||
@@ -107,21 +105,21 @@ Burn the |CL| image onto a USB drive
|
||||
Create a bootable USB drive on macOS\*
|
||||
**************************************
|
||||
|
||||
Make sure you have completed all `Prerequisites`_.
|
||||
* Make sure you completed all `Prerequisites`_.
|
||||
|
||||
Before burning the image onto your USB drive, :ref:`verify-mac` on macOS.
|
||||
* :ref:`verify-mac` on macOS.
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
Burning an image formats the USB drive, and will destroy all pre-existing
|
||||
Burning an image formats the USB drive and destroys all pre-existing
|
||||
content. Back up your data before proceeding.
|
||||
|
||||
#. Launch the Terminal app.
|
||||
#. Open a Terminal window.
|
||||
|
||||
#. Change directory to where the decompressed image is saved.
|
||||
#. Change directory to where the image resides.
|
||||
|
||||
#. Plug in a USB drive and get its identifier:
|
||||
|
||||
@@ -129,7 +127,7 @@ Burn the |CL| image onto a USB drive
|
||||
|
||||
diskutil list
|
||||
|
||||
This will list available disks and their partitions, as shown in Figure 1.
|
||||
This lists available disks and their partitions, as shown in Figure 1.
|
||||
|
||||
.. figure:: /_figures/bootable-usb/bootable-usb-mac-01.png
|
||||
:scale: 100 %
|
||||
@@ -137,21 +135,22 @@ Burn the |CL| image onto a USB drive
|
||||
|
||||
Figure 1: macOS - Get USB drive identifier
|
||||
|
||||
#. Unmount the USB drive identified in the previous step. For example:
|
||||
#. Unmount the USB drive identified in the previous step. For example, to unmount /dev/disk2:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
diskutil umountDisk /dev/disk2
|
||||
|
||||
#. Burn the image onto the drive using the :command:`dd` command.
|
||||
This example uses `./`, your current directory, and it shows how to burn an uncompressed image onto `<your USB device>`:
|
||||
This example uses `./`, your current directory, and it shows how to burn
|
||||
an image onto `<your USB device>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dd if=./clear-[version number]-[image type] of=<your USB device> bs=4m
|
||||
sudo dd if=./clear-[version number]-live-[desktop | server].iso of=<your USB device> bs=4m
|
||||
|
||||
To accelerate the imaging process, add an ‘r’ before the disk identifier.
|
||||
Example: `sudo dd if=./clear-30800-live-server of=/dev/rdisk2 bs=4m`.
|
||||
Example: `sudo dd if=./clear-30800-live-server.iso of=/dev/rdisk2 bs=4m`.
|
||||
|
||||
Press :kbd:`<CTRL>-T` to check imaging progress.
|
||||
|
||||
@@ -163,29 +162,36 @@ Burn the |CL| image onto a USB drive
|
||||
|
||||
.. _bootable-usb-windows:
|
||||
|
||||
Create a bootable USB drive on Windows\*
|
||||
****************************************
|
||||
Create a bootable USB drive on Windows
|
||||
**************************************
|
||||
|
||||
Make sure you have completed all `Prerequisites`_.
|
||||
* Make sure you completed all `Prerequisites`_.
|
||||
|
||||
Before burning the image onto your USB drive, :ref:`verify-windows` on Windows.
|
||||
* :ref:`verify-windows` on Windows\* OS.
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
Burning an image formats the USB drive, and will destroy all pre-existing
|
||||
Burning an image formats the USB drive and destroys all pre-existing
|
||||
content. Back up your data before proceeding.
|
||||
|
||||
#. Download the `Rufus`_ utility to burn the image onto a USB drive.
|
||||
We use Rufus 3.5 here. **Only use the latest version of Rufus**.
|
||||
We use Rufus 3.5 for this example.
|
||||
**Only use the latest version of Rufus**.
|
||||
|
||||
#. Plug in the USB drive and open Rufus.
|
||||
#. Plug in the USB drive.
|
||||
|
||||
#. Launch Rufus.
|
||||
|
||||
#. Under `Device`, select the USB drive.
|
||||
|
||||
#. Under `Boot selection`, click the :guilabel:`SELECT` button.
|
||||
|
||||
#. Find and select the previously extracted |CL| image file.
|
||||
.. note::
|
||||
|
||||
For other image tools, verify the `Volume label` is set to :guilabel:`CLR_ISO` **Do not change the label as installer relies on it.**
|
||||
|
||||
#. Click the :guilabel:`START` button. See Figure 2.
|
||||
|
||||
@@ -204,7 +210,13 @@ Burn the |CL| image onto a USB drive
|
||||
|
||||
Figure 3: ISOHybrid image detected
|
||||
|
||||
#. Select the Windows taskbar menu for USB and select eject.
|
||||
#. Click :guilabel:`OK`.
|
||||
|
||||
#. The process make take more than a few minutes. When the process completes,
|
||||
close Rufus.
|
||||
|
||||
#. Select the Windows taskbar menu for USB and select
|
||||
:guilabel:`Eject <drive name>`.
|
||||
|
||||
.. _Rufus: https://rufus.ie/
|
||||
.. _Downloads: https://clearlinux.org/downloads
|
||||
|
||||
+9
-6
@@ -1,15 +1,18 @@
|
||||
.. _parallels:
|
||||
|
||||
Parallels\* Desktop for Mac\*
|
||||
#############################
|
||||
|CL-ATTR| on Parallels\* Desktop for Mac\*
|
||||
##########################################
|
||||
|
||||
This tutorial describes how to run |CL| Server in
|
||||
:abbr:`CLI (command-line interface)` mode as a guest OS in Parallels Desktop 14
|
||||
for Mac.
|
||||
This page explains how to run |CL| Server in :abbr:`CLI (command-line interface)`
|
||||
mode as a guest OS in Parallels Desktop 14 for Mac.
|
||||
|
||||
Parallels Desktop for Mac is virtualization software that allows other
|
||||
operating systems, such as Linux, to run side-by-side with macOS\*.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
@@ -19,7 +22,7 @@ Download ISO image
|
||||
******************
|
||||
|
||||
#. Download a live-server ISO installation file from https://clearlinux.org/downloads.
|
||||
This tutorial uses |CL| Server 30140 as its example.
|
||||
This guide uses |CL| Server 30140 as its example.
|
||||
|
||||
#. Unzip the ISO image with the command:
|
||||
|
||||
@@ -14,7 +14,7 @@ Overview
|
||||
********
|
||||
|
||||
`VMware Workstation Player`_ is a type 2 hypervisor. It runs on top of
|
||||
Windows\* or Linux\* operating systems. With VMware ESXi, you can
|
||||
Windows\* or Linux\* operating systems. With VMware Workstation Player, you can
|
||||
create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)`
|
||||
on your local system.
|
||||
|
||||
|
||||
@@ -54,16 +54,16 @@ environment settings are respected and no time is wasted trying to resolve a
|
||||
proxy. All these steps happen in the background with no user interaction.
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
***************
|
||||
|
||||
Autoproxy allows |CL| to operate seamlessly behind a proxy
|
||||
because :ref:`swupd <swupd-guide>` and other |CL| tools are implemented on
|
||||
top of libcurl. Tools that do not use libcurl, like git, must
|
||||
be configured independently.
|
||||
be configured independently.
|
||||
|
||||
If you are familiar with PAC files and WPAD, you can use
|
||||
:command:`pacdiscovery` and :command:`FindProxyForURL` to
|
||||
troubleshoot problems with autproxy.
|
||||
troubleshoot problems with autoproxy.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -71,24 +71,29 @@ troubleshoot problems with autproxy.
|
||||
|
||||
.. _findproxyforurl: http://findproxyforurl.com/
|
||||
|
||||
Run :command:`pacdiscovery` with no arguments to indicate
|
||||
|
||||
1. if there is a problem resolving the :command:`WPAD` host name resolution:
|
||||
Run :command:`pacdiscovery` with no arguments to indicate |br|
|
||||
|
||||
#. if there is a problem resolving the :command:`WPAD` host name resolution:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacdiscovery
|
||||
sudo pacdiscovery
|
||||
|
||||
Sample output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
failed getaddrinfo: No address associated with hostname
|
||||
Unable to find wpad host
|
||||
|
||||
2. or if the :command:`pacrunner` service is disabled (masked).
|
||||
#. or if the :command:`pacrunner` service is disabled (masked).
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacdiscovery
|
||||
sudo pacdiscovery
|
||||
|
||||
Sample output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -99,55 +104,65 @@ Unmask the :command:`pacrunner` service by running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl unmask pacrunner.service
|
||||
sudo systemctl unmask pacrunner.service
|
||||
|
||||
:command:`FindProxyForURL` with :command:`busctl` can also indicate if the
|
||||
:command:`pacrunner.service` is masked.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client
|
||||
Use :command:`FindProxyForURL` with :command:`busctl` to indicate |br|
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
FindProxyForURL ss "http://www.google.com" "google.com"
|
||||
Unit pacrunner.service is masked.
|
||||
dig wpad, dig wpad.<domain>
|
||||
#. the URL and port of the proxy server when an external URL and host are
|
||||
provided as arguments:
|
||||
|
||||
:command:`FindProxyForURL` returns the URL and port of the proxy server when
|
||||
an external URL and host are provided as arguments.
|
||||
.. code-block:: bash
|
||||
|
||||
.. code-block:: bash
|
||||
busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
|
||||
|
||||
busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client
|
||||
Sample output showing proxy was found:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: console
|
||||
|
||||
FindProxyForURL ss "http://www.google.com" "google.com"
|
||||
s "PROXY proxy.your.domain.com:<port>"
|
||||
s "PROXY proxy.your.domain.com:<port>"
|
||||
|
||||
If a proxy server is not avialable, or if :command:`pacrunner` is running
|
||||
without a PAC file, :command:`FindProxyForURL` will return "DIRECT".
|
||||
#. if the :command:`pacrunner.service` is masked:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client
|
||||
busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
|
||||
|
||||
.. code-block:: console
|
||||
Sample output:
|
||||
|
||||
FindProxyForURL ss "http://www.google.com" "google.com"
|
||||
s "DIRECT"
|
||||
.. code-block:: console
|
||||
|
||||
Unit pacrunner.service is masked.
|
||||
dig wpad, dig wpad.<domain>
|
||||
|
||||
#. if a proxy server is not available, or if :command:`pacrunner` is running
|
||||
without a PAC file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
|
||||
|
||||
Sample output, indicating connection made directly, without proxy:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
s "DIRECT"
|
||||
|
||||
Once :command:`pacdiscovery` is able to look up :command:`WPAD`, restart the
|
||||
:command:`pacrunner` service:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl stop pacrunner
|
||||
systemctl restart pacdiscovery
|
||||
sudo systemctl stop pacrunner
|
||||
sudo systemctl restart pacdiscovery
|
||||
|
||||
.. note::
|
||||
|
||||
A "domain" or "search" entry in :file:`/etc/resolv.conf` is required
|
||||
for short name lookups to resolve. The :file:`resolv.conf` man page has
|
||||
additional details.
|
||||
additional details.
|
||||
|
||||
.. |br| raw:: html
|
||||
|
||||
<br><br>
|
||||
@@ -16,19 +16,22 @@ tarball and package name to start.
|
||||
Description
|
||||
***********
|
||||
|
||||
The autospec tool attempts to infer the requirements of the :file:`.spec` file
|
||||
by analyzing the source code and :file:`Makefile` information. It
|
||||
continuously runs updated builds based on new information discovered from build
|
||||
failures until it has a complete and valid :file:`.spec` file. If needed, you
|
||||
can influence the behavior of autospec and customize the build by providing
|
||||
optional `control files`_ to the autospec tool.
|
||||
The autospec tool attempts to infer the requirements of the :file:`.spec`
|
||||
file by analyzing the source code and :file:`Makefile` information. It
|
||||
continuously runs updated builds based on new information discovered from
|
||||
build failures until it has a complete and valid :file:`.spec` file. If
|
||||
needed, you can influence the behavior of autospec and customize the build by providing optional `control files`_ to the autospec tool.
|
||||
|
||||
autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_ for
|
||||
additional information on using mock.
|
||||
autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_
|
||||
for additional information on using mock.
|
||||
|
||||
For a general understanding of how an RPM works, visit
|
||||
For a general understanding of how an RPM works, visit
|
||||
the `rpm website`_ or the `RPM Packaging Guide`_.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/qrUpt1D1YAw" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen style="padding:10px; background-color: #fff;"></iframe>
|
||||
|
||||
How it works
|
||||
************
|
||||
|
||||
@@ -52,13 +55,11 @@ Create an RPM
|
||||
|
||||
The basic autospec process is described in the following steps:
|
||||
|
||||
#. The :command:`make autospec` command generates a :file:`.spec` file based on
|
||||
the analysis of code and existing control files.
|
||||
#. The :command:`make autospec` command generates a :file:`.spec` file based
|
||||
on the analysis of code and existing control files.
|
||||
|
||||
Any control files should be located in the same directory as the resulting
|
||||
:file:`.spec` file.
|
||||
|
||||
View the `autospec README`_ for more information on `control files`_.
|
||||
:file:`.spec` file. View the `autospec README`_ for more information on `control files`_.
|
||||
|
||||
#. autospec creates a build root with mock config.
|
||||
|
||||
@@ -99,8 +100,8 @@ Complete `Setup environment to build source`_ before using these examples.
|
||||
Example 1: Build RPM with an existing spec file
|
||||
===============================================
|
||||
|
||||
This example shows how to build a RPM from a pre-packaged upstream package with
|
||||
an existing spec file. The example uses the ``dmidecode`` package.
|
||||
This example shows how to build a RPM from a pre-packaged upstream package
|
||||
with an existing spec file. The example uses the ``dmidecode`` package.
|
||||
|
||||
#. Navigate to the autospec workspace and clone the ``dmidecode`` package:
|
||||
|
||||
@@ -129,8 +130,8 @@ an existing spec file. The example uses the ``dmidecode`` package.
|
||||
cd ~/clearlinux/packages/dmidecode/
|
||||
make build
|
||||
|
||||
#. The resulting RPMs are in :file:`./rpms`. Build logs and additional RPMs are
|
||||
in :file:`./results`.
|
||||
#. The resulting RPMs are in :file:`./rpms`. Build logs and additional RPMs
|
||||
are in :file:`./results`.
|
||||
|
||||
Example 2: Build a new RPM
|
||||
==========================
|
||||
@@ -140,23 +141,23 @@ create a simple helloclear RPM.
|
||||
|
||||
#. Navigate to the autospec workspace and build the helloclear RPM. The
|
||||
:file:`Makefile` provides a :command:`make autospecnew` that can
|
||||
automatically generate an RPM package using the autospec tool. You must pass
|
||||
the URL to the source tarball and the NAME of the RPM you wish to create:
|
||||
automatically generate an RPM package using the autospec tool. You must
|
||||
pass the URL to the source tarball and the NAME of the RPM you wish to
|
||||
create:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/clearlinux
|
||||
make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz" NAME="helloclear"
|
||||
|
||||
The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and
|
||||
additional RPMs are in :file:`./packages/helloclear/results`.
|
||||
The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and additional RPMs are in :file:`./packages/helloclear/results`.
|
||||
|
||||
Example 3: Generate a new spec file with a pre-defined package
|
||||
==============================================================
|
||||
|
||||
This example shows how to modify an existing package to create a custom RPM. In
|
||||
this example you will make a simple change to the ``dmidecode`` package and
|
||||
rebuild the package.
|
||||
This example shows how to modify an existing package to create a custom RPM.
|
||||
In this example you will make a simple change to the ``dmidecode`` package
|
||||
and rebuild the package.
|
||||
|
||||
#. Navigate to the autospec workspace and clone the ``dmidecode`` package:
|
||||
|
||||
@@ -187,7 +188,8 @@ rebuild the package.
|
||||
These files aren't needed by dmidecode, so we can remove them without
|
||||
any issues.
|
||||
|
||||
#. In the :file:`dmidecode` directory, build the modified ``dmidecode`` package:
|
||||
#. In the :file:`dmidecode` directory, build the modified ``dmidecode``
|
||||
package:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -199,8 +201,8 @@ Example 4: Provide control files to autospec
|
||||
============================================
|
||||
|
||||
This example shows how to modify control files to correct build failures that
|
||||
autospec is unable to resolve. In this example, you will add a missing license
|
||||
and dependencies so autospec can complete a successful build.
|
||||
autospec is unable to resolve. In this example, you will add a missing
|
||||
license and dependencies so autospec can complete a successful build.
|
||||
|
||||
#. Navigate to the autospec workspace:
|
||||
|
||||
@@ -218,8 +220,8 @@ and dependencies so autospec can complete a successful build.
|
||||
|
||||
.. note::
|
||||
|
||||
In a later step of this example, we will search the cloned package repos
|
||||
for a missing dependency.
|
||||
In a later step of this example, we will search the cloned package
|
||||
repos for a missing dependency.
|
||||
|
||||
#. Build the opae-sdk RPM:
|
||||
|
||||
@@ -241,7 +243,7 @@ and dependencies so autospec can complete a successful build.
|
||||
|
||||
#. Add one or more valid license identifiers from the
|
||||
`SPDX License List <https://spdx.org/licenses/>`_.
|
||||
In the example below, two different licenses are appropriate based on the
|
||||
In the example below, two different licenses are appropriate based on the
|
||||
opae-sdk project licensing:
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -271,7 +273,9 @@ and dependencies so autospec can complete a successful build.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
CMake Error: The following variables are used in this project, but they are set to NOTFOUND. Please set them or make sure they are set and tested correctly in the CMake files:
|
||||
CMake Error: The following variables are used in this project, but
|
||||
they are set to NOTFOUND. Please set them or make sure they are set and tested correctly in the CMake files:
|
||||
|
||||
CJSON_LIBRARY
|
||||
linked by target "opae-c++-utils" in directory /builddir/build/BUILD/opae-sdk-0.13.0/tools/c++utilslib
|
||||
json-c_LIBRARIES
|
||||
@@ -279,9 +283,8 @@ and dependencies so autospec can complete a successful build.
|
||||
libuuid_LIBRARIES
|
||||
linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae
|
||||
|
||||
#. Search the spec files of upstream |CL| packages to see if the json-c library
|
||||
is available. In this case, it does exist and we'll add the json-c 'dev'
|
||||
package into the buildreq_add:
|
||||
#. Search the spec files of upstream |CL| packages to see if the json-c
|
||||
library is available. In this case, it does exist and we'll add the json-c 'dev' package into the buildreq_add:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -290,31 +293,26 @@ and dependencies so autospec can complete a successful build.
|
||||
|
||||
.. note::
|
||||
|
||||
This search step works only if the user cloned all of the upstream package
|
||||
repos. In this example, upstream package repos were cloned in a previous
|
||||
step.
|
||||
This search step works only if the user cloned all of the upstream package repos. In this example, upstream package repos were cloned in a previous step.
|
||||
|
||||
#. Search the spec files of upstream |CL| packages to see if the libuuid library
|
||||
is available. In this case, it exists in the util-linux package, so we'll add
|
||||
util-linux-dev package into the buildreq_add:
|
||||
#. Search the spec files of upstream |CL| packages to see if the libuuid
|
||||
library is available. In this case, it exists in the util-linux package, so we'll add util-linux-dev package into the buildreq_add:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
grep 'libuuid\.so$' ~/clearlinux/packages/*/*.spec
|
||||
echo "util-linux-dev" >> buildreq_add
|
||||
|
||||
#. Run autospec again and find the successfully-generated RPMs in the :file:`rpms`
|
||||
directory:
|
||||
#. Run autospec again and find the successfully-generated RPMs in the
|
||||
:file:`rpms` directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make autospec
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
If you need a dependency that does not exist in the |CL| repo, you must first
|
||||
build it manually (see `Example 2: Build a new RPM`_), then add the repo so
|
||||
that autospec knows the package exists. For example:
|
||||
If you need a dependency that does not exist in the |CL| repo, you must first build it manually (see `Example 2: Build a new RPM`_), then add the repo so that autospec knows the package exists. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -322,9 +320,102 @@ and dependencies so autospec can complete a successful build.
|
||||
make repoadd
|
||||
make repostatus
|
||||
|
||||
You only need to add the dependency to the :file:`buildreq_add` control file
|
||||
if autospec is not able to automatically find the correct dependency on its
|
||||
own.
|
||||
You only need to add the dependency to the :file:`buildreq_add` control
|
||||
file if autospec is not able to automatically find the correct dependency
|
||||
on its own.
|
||||
|
||||
.. TODO: Document how to set up a license server for use with autospec.
|
||||
.. TODO: Demonstrate control file management. Establish specific use cases.
|
||||
|
||||
Example 5: Update an existing package
|
||||
=====================================
|
||||
|
||||
The |CL| team prefers to carry no patches and seeks to make the latest
|
||||
releases work. If we do need patches, we use :command:`autospec` to add,
|
||||
remove, or manage patches. The :command:`autospec` control files are
|
||||
integral to the patch management process. Developers can expect a more
|
||||
streamlined approach to managing a large collection of packages with
|
||||
:command:`autospec`.
|
||||
|
||||
Adding and submitting patches
|
||||
-----------------------------
|
||||
|
||||
* To add patches to |CL| upstream, follow `patching source code`_.
|
||||
|
||||
* To submit a patch to upstream, follow
|
||||
`contributing to an existing software package`_.
|
||||
|
||||
If you maintain a downstream derivative of |CL| and you want to integrate
|
||||
new or patched packages into your mix, follow the process in :ref:`mixer`.
|
||||
|
||||
Assuming you have followed the above process, :command:`autospec` has
|
||||
generated a new spec file.
|
||||
|
||||
Refresh a package and inspect
|
||||
-----------------------------
|
||||
|
||||
In this example, we use autospec to refresh the :command:`m4` package and
|
||||
recreate RPM files.
|
||||
|
||||
#. Navigate to the top-level directory of the workspace
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd clearlinux
|
||||
|
||||
- where :command:`clearlinux` is the top level of the tooling workspace
|
||||
|
||||
#. Run the make_clone command and then navigate to the package.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make clone_m4
|
||||
|
||||
cd packages/m4
|
||||
|
||||
#. Make desired changes to the package, its control files, or
|
||||
other files.
|
||||
|
||||
#. Finally, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make autospec
|
||||
|
||||
#. To view spec file changes, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git show m4.spec
|
||||
|
||||
The output shows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
m4: Autospec creation for version 1.4.18
|
||||
|
||||
diff --git a/m4.spec b/m4.spec
|
||||
index f76c78d..97b846a 100644
|
||||
--- a/m4.spec
|
||||
+++ b/m4.spec
|
||||
@@ -6,15 +6,14 @@
|
||||
#
|
||||
Name : m4
|
||||
Version : 1.4.18
|
||||
-Release : 88
|
||||
+Release : 89
|
||||
URL : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz
|
||||
Source0 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz
|
||||
-Source99 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig
|
||||
+Source1 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig
|
||||
Summary : No detailed summary available
|
||||
Group : Development/Tools
|
||||
...
|
||||
|
||||
#. The following commands provide a more complete view of the changes.
|
||||
|
||||
* :command:`git log -p`
|
||||
* :command:`gitk`
|
||||
|
||||
Test packaged software
|
||||
**********************
|
||||
@@ -338,7 +429,7 @@ generated RPMs.
|
||||
|
||||
.. note::
|
||||
The methods outlined below should only be used for temporary testing on
|
||||
development systems.
|
||||
development systems.
|
||||
|
||||
|
||||
Test in a |CL| virtual machine
|
||||
@@ -346,7 +437,7 @@ Test in a |CL| virtual machine
|
||||
|
||||
The |CL| development tooling includes a method to install RPMs into a |CL|
|
||||
virtual machine running on the KVM hypervisor. Using a :abbr:`VM (Virtual
|
||||
Machine)` allows testing in a completely isolated environment.
|
||||
Machine)` allows testing in a completely isolated environment.
|
||||
|
||||
To test an autospec-created package inside a VM:
|
||||
|
||||
@@ -402,8 +493,8 @@ To test an autospec-created package inside a VM:
|
||||
deleted:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
poweroff
|
||||
|
||||
poweroff
|
||||
rm clear.img
|
||||
|
||||
|
||||
@@ -504,9 +595,16 @@ Related topics
|
||||
|
||||
* :ref:`Mixer tool <mixer>`
|
||||
|
||||
.. _contributing to an existing software package: https://github.com/clearlinux/distribution/blob/master/contributing.md#contributing-to-an-existing-software-package
|
||||
|
||||
.. _patching source code: https://github.com/clearlinux/distribution/blob/master/contributing.md#patching-source-code
|
||||
|
||||
.. _`Makefile.common`: https://github.com/clearlinux/common/blob/master/Makefile.common
|
||||
.. _autospec README: https://github.com/clearlinux/autospec
|
||||
.. _control files: https://github.com/clearlinux/autospec#control-files
|
||||
.. _mock wiki: https://github.com/rpm-software-management/mock/wiki
|
||||
.. _rpm website: http://rpm.org
|
||||
.. _RPM Packaging Guide: https://rpm-packaging-guide.github.io/
|
||||
|
||||
|
||||
.. TODO: Add link to how to submit a new package: https://github.com/clearlinux/distribution/blob/master/contributing.md#contributing-a-new-software-package
|
||||
+374
-117
@@ -26,7 +26,7 @@ will be part of your update. You can select content from each of these sources t
|
||||
|
||||
The update content that mixer generates consists of various pieces of OS
|
||||
content, update metadata, as well as a complete image. The OS content
|
||||
includes all files in an update, as well as zero- and delta-packs for improved update performance. The update metadata, stored as manifests, describes all of the bundle information for the update. Update content produced by mixer is then published to a web server and consumed by clients via swupd. Refer to :ref:`swupd <swupd-guide>` for additional information regarding updates and update content.
|
||||
includes all files in an update, as well as zero- and delta-packs for improved update performance. The update metadata, stored as manifests, describes all of the bundle information for the update. Update content produced by mixer is then published to a web server and consumed by clients via :command:`swupd`. Refer to :ref:`swupd <swupd-guide>` for additional information regarding updates and update content.
|
||||
|
||||
How it works
|
||||
************
|
||||
@@ -42,7 +42,7 @@ Prerequisites
|
||||
|
||||
* :command:`mixer` bundle
|
||||
|
||||
Add the mixer tool with the :command:`mixer` bundle. Refer to
|
||||
Add the mixer tool by installing the :command:`mixer` bundle. Refer to
|
||||
:ref:`swupd-guide` for more information on installing bundles.
|
||||
|
||||
* Docker\* container
|
||||
@@ -67,9 +67,7 @@ Prerequisites
|
||||
|
||||
* Location to host the update content and images
|
||||
|
||||
In order for swupd to make use of your mix, the update content for your mix
|
||||
must be hosted on a web server. Your mix will be configured with an update
|
||||
location URL, which swupd will use to pull down updates.
|
||||
In order for :command:`swupd` to make use of your mix, the update content for your mix must be hosted on a web server. Your mix will be configured with an update location URL, which :command:`swupd` will use to pull down updates.
|
||||
|
||||
Refer to `Set up a nginx web server for mixer`_ for an simple example of
|
||||
setting up an update location.
|
||||
@@ -107,11 +105,9 @@ the setup before you create a mix.
|
||||
#. Edit builder.conf.
|
||||
|
||||
:file:`builder.conf` tells the mixer tool how to configure the mix. For
|
||||
example, it allows you to configure where mixer output is located and where
|
||||
swupd update content will be located.
|
||||
example, it allows you to configure where mixer output is located and where swupd update content will be located.
|
||||
|
||||
At minimum, set the URL of your update server so your custom OS knows where
|
||||
to get update content.
|
||||
At minimum, set the URL of your update server so your custom OS knows where to get update content.
|
||||
|
||||
Refer to the `builder.conf`_ section for more information.
|
||||
|
||||
@@ -172,7 +168,7 @@ A mix is created with the following steps:
|
||||
|
||||
Deploy update content and images to your update server.
|
||||
|
||||
View the `Example 3: Deploy updates to target`_ for a simple deployment
|
||||
View the `Example 5: Deploy updates to target`_ for a simple deployment
|
||||
scenario.
|
||||
|
||||
Maintain or modify mix
|
||||
@@ -195,47 +191,76 @@ use:
|
||||
Complete all `Prerequisites`_ before using these examples.
|
||||
|
||||
Example 1: Mix set up
|
||||
======================
|
||||
=====================
|
||||
|
||||
This example shows the basic steps for the first-time setup of
|
||||
This example shows the basic steps for the first-time setup of
|
||||
mixer for a new mix.
|
||||
|
||||
#. Create an empty directory to use as a workspace for mixer:
|
||||
#. Create a directory to use as a workspace for mixer:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir ~/mixer
|
||||
|
||||
#. In your mixer workspace, generate an initial mix based on the latest upstream
|
||||
|CL| version, with minimum bundles. In the initialization output, be aware
|
||||
that your initial mix version is set to 10 and that the minimum bundles have
|
||||
been added.
|
||||
#. In your mixer workspace, generate an initial mix based on the latest
|
||||
upstream |CL| version, with minimum bundles. In the initialization
|
||||
output, be aware that your initial mix version is set to 10 and that the
|
||||
minimum bundles have been added.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/mixer
|
||||
mixer init
|
||||
|
||||
#. Edit :file:`builder.conf` to set the value of CONTENTURL and VERSIONURL to
|
||||
the IP address of the nginx\* server you set up in the prerequisite
|
||||
`Set up a nginx web server for mixer`_. For example:
|
||||
.. note::
|
||||
|
||||
If you want to add all upstream bundles in your mix,
|
||||
initialize your mix as shown below.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer init --all-upstream
|
||||
|
||||
#. Look up your IP address:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
networkctl status
|
||||
|
||||
#. Copy the IP “Address”, from above, for the next step.
|
||||
|
||||
.. note::
|
||||
|
||||
In this example, we put `mixer` and `nginx` on the same system. In a production environment, they would likely reside on different systems.
|
||||
|
||||
#. Edit :file:`builder.conf`. Paste the IP address from the previous step
|
||||
as the value after \http:// for CONTENTURL and VERSIONURL. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
CONTENTURL="http://192.168.25.52"
|
||||
VERSIONURL="http://192.168.25.52"
|
||||
|
||||
#. `Set up a nginx web server for mixer`_.
|
||||
|
||||
|
||||
Example 2: Create a simple mix
|
||||
==============================
|
||||
|
||||
This example shows how to create a simple custom mix using upstream content.
|
||||
We'll create an image for a QEMU virtual machine that we can use later to test
|
||||
our mix.
|
||||
We'll create an image for a QEMU virtual machine that we can use later to
|
||||
test our mix.
|
||||
|
||||
We can use the default bundles that were added during initialization, but these
|
||||
include the :command:`native-kernel` bundle that is intended to be used on a
|
||||
bare metal system instead of a VM. So we will modify the default bundle
|
||||
set to get a smaller kernel image, which will also be faster to load.
|
||||
We can use the default bundles that were added during initialization, but
|
||||
these include the :command:`native-kernel` bundle that is intended to be
|
||||
used on a bare metal system instead of a VM. So we will modify the default
|
||||
bundle set to get a smaller kernel image, which will also be faster to load.
|
||||
|
||||
The only bundles available to :command:`swupd` for a given release are those
|
||||
that were added to the mix during build time. A mix doesn’t automatically
|
||||
inherit upstream bundles.
|
||||
|
||||
#. Assure that you have run `mixer init`, shown in Example 1.
|
||||
|
||||
#. Update bundles in mix:
|
||||
|
||||
@@ -244,8 +269,11 @@ set to get a smaller kernel image, which will also be faster to load.
|
||||
mixer bundle remove kernel-native
|
||||
mixer bundle add kernel-kvm
|
||||
|
||||
.. note::
|
||||
The mixer bundle commands operate on the bundle description files but not on the bundle contents. To remove bundle contents and their tracking completely, follow `Example 6: Remove a bundle from client system`_, Advanced.
|
||||
|
||||
#. In this case, we will add the `editors` bundle from upstream, but we will
|
||||
remove the `joe` editor.
|
||||
remove the :command:`joe` editor.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -258,63 +286,112 @@ set to get a smaller kernel image, which will also be faster to load.
|
||||
|
||||
$EDITOR ./local-bundles/editors
|
||||
|
||||
#. List the bundles in the mix again to confirm removal.
|
||||
#. List the bundles in the mix again to confirm removal of :command:`joe`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer bundle list --tree
|
||||
|
||||
|
||||
#. Build bundles:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer build bundles
|
||||
|
||||
Look in ~/mixer/update/image/<mix version>/full for the full chroot after the
|
||||
:command:`build` command completes.
|
||||
|
||||
#. Build update content. Browse to your \http://localhost site and you'll see
|
||||
the web page is now up, but with no update content. Build the update content:
|
||||
#. First, browse to web server from Example 1. The web page appears yet
|
||||
has no update content. Build the update content:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer build update
|
||||
|
||||
Refresh your \http://localhost site and now you can see the update
|
||||
After that is completed, on your web server, you can see the update
|
||||
content for mix version 10.
|
||||
|
||||
Look in ~/mixer/update/www/<mix version> to see the update content in your
|
||||
workspace.
|
||||
Example 3: Create an update for your mix
|
||||
========================================
|
||||
|
||||
#. Configure image. Edit the ister configuration file for your image to include
|
||||
all of the bundles you want preinstalled in the image. If this is the first
|
||||
time creating an image, first get a copy of the
|
||||
Next, let’s create a new version of the mix. We’ll add a new bundle.
|
||||
|
||||
#. Create a new version of your mix, for the live image to
|
||||
update to. Increment your mix version by 10:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer versions update
|
||||
|
||||
#. Add the upstream :command:`curl` bundle to version 20 of the mix:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer bundle add curl
|
||||
|
||||
#. Build your next mix version that incorporates the new bundle.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer build bundles
|
||||
mixer build update
|
||||
|
||||
#. Optionally, you can build delta-packs, which help reduce client update
|
||||
time:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer build delta-packs --from 10 --to 20
|
||||
|
||||
Refresh your web server to see the update content for mix version 20.
|
||||
|
||||
You can also look in ~/mixer/update/www/<mix version> to see the update
|
||||
content in your workspace.
|
||||
|
||||
|
||||
Example 4: Build an image
|
||||
=========================
|
||||
|
||||
This example shows how to build a bootable image containing the
|
||||
:command:`kernel-kvm`, :command:`os-core`, and the :command:`os-core-update`
|
||||
bundles from Example 2. Underneath, mixer uses `ister`_ to generate the
|
||||
image.
|
||||
|
||||
#. Change directory into your mix.
|
||||
|
||||
#. Configure image.
|
||||
|
||||
Edit the ister configuration file for your image to include all of the bundles you want pre-installed in the image. If this is the first time creating an image, first get a copy of the
|
||||
:file:`release-image-config.json` template file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl -O https://raw.githubusercontent.com/bryteise/ister/master/release-image-config.json
|
||||
|
||||
For this example, edit :file:`release-image-config.json` so that the root
|
||||
partition size is "5G" and replace the "kernel-native" bundle with
|
||||
"kernel-kvm".
|
||||
For this example, make the following revisions
|
||||
:file:`release-image-config.json`:
|
||||
|
||||
.. code-block:: console
|
||||
* Set root partition size to "5G"
|
||||
* Replace the "kernel-native" bundle with "kernel-kvm"
|
||||
* Set the version to 10 (as an integer)
|
||||
|
||||
.. note::
|
||||
When creating an image, select a subset of the bundles that are part of your mix. All the bundles that are *not* part of this subset are available for consumers of that image to install afterwards via swupd.
|
||||
|
||||
.. code-block:: bash
|
||||
:linenos:
|
||||
:emphasize-lines: 5,11-12
|
||||
|
||||
{
|
||||
"DestinationType" : "virtual",
|
||||
"DestinationType" : "virtual",
|
||||
"PartitionLayout" : [ { "disk" : "release.img", "partition" : 1, "size" : "32M", "type" : "EFI" },
|
||||
{ "disk" : "release.img", "partition" : 2, "size" : "16M", "type" : "swap" },
|
||||
{ "disk" : "release.img", "partition" : 3, "size" : "5G", "type" : "linux" } ],
|
||||
"FilesystemTypes" : [ { "disk" : "release.img", "partition" : 1, "type" : "vfat" },
|
||||
{ "disk" : "release.img", "partition" : 2, "type" : "swap" },
|
||||
{ "disk" : "release.img", "partition" : 3, "type" : "ext4" } ],
|
||||
{ "disk" : "release.img", "partition" : 2, "size" : "16M", "type" : "swap" },
|
||||
{ "disk" : "release.img", "partition" : 3, "size" : "5G", "type" : "linux" } ],
|
||||
"FilesystemTypes" : [ { "disk" : "release.img", "partition" : 1, "type" : "vfat" },
|
||||
{ "disk" : "release.img", "partition" : 2, "type" : "swap" },
|
||||
{ "disk" : "release.img", "partition" : 3, "type" : "ext4" } ],
|
||||
"PartitionMountPoints" : [ { "disk" : "release.img", "partition" : 1, "mount" : "/boot" },
|
||||
{ "disk" : "release.img", "partition" : 3, "mount" : "/" } ],
|
||||
"Version": "latest",
|
||||
{ "disk" : "release.img", "partition" : 3, "mount" : "/" } ],
|
||||
"Version": 10,
|
||||
"Bundles": ["kernel-kvm", "os-core", "os-core-update"]
|
||||
}
|
||||
}
|
||||
|
||||
#. Build the image.
|
||||
|
||||
@@ -322,41 +399,15 @@ set to get a smaller kernel image, which will also be faster to load.
|
||||
|
||||
sudo mixer build image
|
||||
|
||||
The output from this step will be :file:`release.img`, which is a live image.
|
||||
The output from this step will be :file:`release.img`, which is a live
|
||||
image.
|
||||
|
||||
#. Make the next mix. Create a new version of your mix, for the live image to
|
||||
update to. Increment your mix version by 10:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer versions update
|
||||
|
||||
Repeat steps 1-3 to add the upstream :command:`curl` bundle to the mix:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer bundle add curl
|
||||
mixer build bundles
|
||||
mixer build update
|
||||
|
||||
Build optional delta-packs, which helps reduce client update time:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer build delta-packs --from 10 --to 20
|
||||
|
||||
Refresh your \http://localhost site to see the update content for
|
||||
mix version 20.
|
||||
|
||||
Look in ~/mixer/update/www/<mix version> to see the update content in your
|
||||
workspace.
|
||||
|
||||
Example 3: Deploy updates to target
|
||||
Example 5: Deploy updates to target
|
||||
===================================
|
||||
|
||||
The image created in Example 2 is directly bootable in QEMU. In this example,
|
||||
we'll boot the image from Example 2 to verify it, and update the image from
|
||||
mix version 10 (from which the image was built), to mix version 20.
|
||||
The image created in Example 4 is directly bootable in QEMU. In this example,
|
||||
we'll boot the image and verify it. Then we'll update the image from
|
||||
mix version 10 to mix version 20.
|
||||
|
||||
#. Set up the QEMU environment.
|
||||
|
||||
@@ -366,8 +417,8 @@ mix version 10 (from which the image was built), to mix version 20.
|
||||
|
||||
sudo swupd bundle-add kvm-host
|
||||
|
||||
Get the virtual EFI firmware, download the image launch script, and make it
|
||||
executable:
|
||||
#. Get the virtual EFI firmware, download the image launch script, and make
|
||||
it executable:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -375,13 +426,29 @@ mix version 10 (from which the image was built), to mix version 20.
|
||||
curl -O https://download.clearlinux.org/image/start_qemu.sh
|
||||
chmod +x start_qemu.sh
|
||||
|
||||
#. Start your VM image (created in Example 2):
|
||||
#. Start your VM image (created in Example 4):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ./start_qemu.sh release.img
|
||||
|
||||
#. Log in as root and set a password
|
||||
#. Log in as root and set a password.
|
||||
|
||||
#. To avoid adding a flag each time, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir -p /etc/swupd
|
||||
cat > /etc/swupd/config << EOF
|
||||
[GLOBAL]
|
||||
allow_insecure_http=true
|
||||
EOF
|
||||
|
||||
.. note:
|
||||
|
||||
By default, the swupd client is designed to communicate with an
|
||||
*\https* server. For development purposes, the swupd client can talk to
|
||||
an *\http* server if you add the flag :command:`--allow-insecure-http`.
|
||||
|
||||
#. Try out your mix.
|
||||
|
||||
@@ -391,19 +458,31 @@ mix version 10 (from which the image was built), to mix version 20.
|
||||
|
||||
swupd info
|
||||
swupd bundle-list
|
||||
swupd bundle-list -a
|
||||
|
||||
#. Now we will add the `editors` bundle that we modified.
|
||||
#. List available bundles on your update server.
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
swupd bundle add editors
|
||||
swupd bundle-list -a
|
||||
|
||||
#. Try to start the `joe` editor. It should not appear because we removed it
|
||||
from the original `editors` bundle.
|
||||
#. Now we will add the :command:`editors` bundle that we modified.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
swupd bundle-add editors
|
||||
|
||||
#. Try to start the :command:`joe` editor.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
joe
|
||||
|
||||
It should not appear. We removed it from the original
|
||||
:command:`editors` bundle.
|
||||
|
||||
#. Next we will update from version 10 to 20 to capture the newly
|
||||
available bundles. Use :command:`swupd` to update your mix:
|
||||
available bundles.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -411,7 +490,7 @@ mix version 10 (from which the image was built), to mix version 20.
|
||||
swupd update
|
||||
swupd bundle-list -a
|
||||
|
||||
#. Now your mix should be at version 20 and curl is now available. Try using
|
||||
#. Now your mix should be at version 20 and curl is available. Try using
|
||||
curl. This will fail because curl is not yet installed:
|
||||
|
||||
.. code-block:: console
|
||||
@@ -419,19 +498,184 @@ mix version 10 (from which the image was built), to mix version 20.
|
||||
curl: command not found
|
||||
To install curl use: swupd bundle-add curl
|
||||
|
||||
Add the new bundle from your update server to your VM. Retry curl. It works!
|
||||
#. Add the new bundle from your update server to your VM. Retry curl.
|
||||
It works!
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
swupd bundle-add curl
|
||||
curl -O https://download.clearlinux.org/image/start_qemu.sh
|
||||
|
||||
Shutdown your VM:
|
||||
#. Shutdown your VM:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
poweroff
|
||||
|
||||
Example 6: Remove a bundle from client system
|
||||
=============================================
|
||||
|
||||
Removing a bundle in a future release requires more steps than deleting the
|
||||
bundle description file, as shown in Example 2. After a bundle is built in
|
||||
the mix, you must assure all of the files that are part of the bundle are
|
||||
removed from the client where that bundle is installed. To do this, create a
|
||||
version of this bundle in which all of its content is marked for deletion.
|
||||
|
||||
In the following example, we show how to remove the contents of the `editors`
|
||||
bundle that we added to our mix in Example 2.
|
||||
|
||||
#. First update your mix version. This will set the mix to the next version.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer versions update
|
||||
|
||||
.. note::
|
||||
Run this command every time that you want to build a new version.
|
||||
|
||||
#. Navigate to local-bundles:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd local-bundles
|
||||
|
||||
#. Open the `editors` bundle with an editor and delete
|
||||
**all lines** that follow after the `[MAINTAINERS]` line.
|
||||
|
||||
#. Afterward, it should look like this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# [TITLE]: editors
|
||||
# [DESCRIPTION]: Run popular terminal text editors.
|
||||
# [STATUS]: Active
|
||||
# [CAPABILITIES]:
|
||||
# [TAGS]: Tools and Utilities, Editor
|
||||
# [MAINTAINER]: Developer <developer@intel.com>
|
||||
|
||||
#. Save and exit.
|
||||
|
||||
#. Next, run a build to capture recently edited bundles and update your mix.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer build all
|
||||
|
||||
.. note::
|
||||
:command:`mixer build all` runs both :command:`mixer build bundles` and :command:`mixer build update` in one step.
|
||||
|
||||
At this point the new mix, version 30, is complete. All the content of the
|
||||
editors bundles is marked as deleted. If any clients of this mix upgraded to
|
||||
mix build version 30, the content of the editors bundle would be removed.
|
||||
Note that the bundle still exists and is being tracked by :command:`swupd`,
|
||||
but it contains no files.
|
||||
|
||||
Example 7: Execute a format bump
|
||||
================================
|
||||
|
||||
As a maintainer of your mix, you must execute a format bump if you wish to:
|
||||
|
||||
* Track upstream’s format bump on your downstream derivative
|
||||
* Delete any custom bundles that were added
|
||||
|
||||
Follow the appropriate use case below depending on your needs.
|
||||
|
||||
Basic
|
||||
-----
|
||||
|
||||
If you maintain your own downstream derivative and you want to track
|
||||
upstream, you need to do a format bump when one occurs on upstream. This
|
||||
method helps you track the latest changes on upstream; however, it does not
|
||||
change any local content that was added or deleted. For example, if you
|
||||
deprecated bundles, this method will **not remove the bundle tracking**.
|
||||
Refer to `Advanced`_ for help on managing your local mix and removing bundle
|
||||
tracking.
|
||||
|
||||
In this example, we show a mix version that was initialized to upstream
|
||||
version 29740 (format 27). You need to update your mix to upstream version
|
||||
30700 (format 28). To do so, you will go through a format bump.
|
||||
|
||||
#. Change to your mix location and verify the current version of the mix and
|
||||
its format.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer versions
|
||||
|
||||
#. Update to upstream version, which has a newer format.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer versions update --upstream-version 30700
|
||||
|
||||
The output will look like this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
Old mix: 10
|
||||
Old upstream: 29740 (format: 27)
|
||||
|
||||
New mix: 20
|
||||
New upstream: 30700 (format: 28)
|
||||
[...]
|
||||
|
||||
Read the output carefully:
|
||||
|
||||
* The Old mix shows the current version (10) of your mix.
|
||||
|
||||
* The Old upstream shows the version and format (27) on which it’s based.
|
||||
|
||||
* The New mix shows the new version (20) of your mix.
|
||||
|
||||
* The New upstream shows the version and format (28) on which it’s based.
|
||||
|
||||
#. Given that the format in the output differs, you need to run a
|
||||
format bump:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer build upstream-format --new-format 28
|
||||
|
||||
.. note::
|
||||
|
||||
You specify the :command:`--new-format` to indicate the format (28) to which you transition.
|
||||
|
||||
#. Your mix is now synchronized with the new format (28); however, you must
|
||||
still advance to the desired or latest version.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer versions update --upstream-version 30700
|
||||
|
||||
Advanced
|
||||
--------
|
||||
|
||||
To properly remove a bundle from being tracked by :command:`swupd`,
|
||||
do a manual format bump. This process can also be used to perform
|
||||
customizations during the update, such as:
|
||||
|
||||
* Adjustment in the command parameters
|
||||
|
||||
* Change the content of the chroot
|
||||
|
||||
Tutorial
|
||||
--------
|
||||
|
||||
Try this tutorial to learn how to manually do a format bump. Read the
|
||||
comments above each line for an explanation of each step as you execute
|
||||
commands. Use this same process on your mix if you need to remove a bundle
|
||||
and its tracking.
|
||||
|
||||
The `afb.sh reference script`_ shows an example of how to:
|
||||
|
||||
* Create a mix
|
||||
|
||||
* Add a bundle
|
||||
|
||||
* Deprecate a bundle
|
||||
|
||||
* Do a format bump to remove the deprecated bundle
|
||||
|
||||
|
||||
.. Example: Create a mix with custom RPM
|
||||
.. -------------------------------------
|
||||
@@ -560,29 +804,38 @@ other version within that epoch. The compatibility epoch is set as the
|
||||
:file:`mixer.state` are used by mixer between executions and should not be
|
||||
manually changed.
|
||||
|
||||
A format bump is like modifying the foundation of a house to create a new
|
||||
level. If `Format` increments to a new epoch (a "format bump"), the OS has
|
||||
changed in such a way that updating from build A in format X to build B in
|
||||
format Y will not work.
|
||||
Format bump
|
||||
-----------
|
||||
|
||||
A format bump is required when:
|
||||
Mixer needs to produce content that is consumable by swupd. For swupd to
|
||||
consume the content, it needs a consistent protocol that describes the
|
||||
requirements of the Manifest.
|
||||
|
||||
* The software updater, :command:`swupd`, or the software is no longer
|
||||
compatible with the previous update scheme
|
||||
If the `Format` increments to a new epoch (a "format bump"), the underlying
|
||||
`swupd` protocol has changed such that updating from one build version in an
|
||||
old format to a new build version in a new format is **only** allowed if one
|
||||
performs a corresponding format bump.
|
||||
|
||||
* A package is removed from the update stream and the update must ensure the
|
||||
files associated with that package are removed from the system
|
||||
Format bumps are “checkpoints” (see Figure 1). The first release (20) is
|
||||
built on the previous format with a `swupd` that is capable of interpreting
|
||||
the next format. The second release (30) has the same content, but it’s
|
||||
built in the new format.
|
||||
|
||||
Using a format increment, we make sure pre- and co-requisite changes flow out
|
||||
with proper ordering. The updated client will only update to the latest
|
||||
release in its respective format version, unless overridden by command line
|
||||
flags. In this way, we can guarantee that all clients update to the final
|
||||
version in their given format.
|
||||
Suppose you have build version 10, but you need the tools in build version
|
||||
40. Whereas version 10 belongs to Format 27, version 40 belongs to Format
|
||||
28. The swupd client needs to follow formats sequentially. First, you must
|
||||
update to version 20, which effectively enables a format bump to version 30.
|
||||
Doing a format bump bridges the gap so your mix can progress to build
|
||||
version 40.
|
||||
|
||||
The given format *must* contain all the changes needed to understand the content built in the next format. Only after reaching the final release in the old format can a client continue to update to releases in the new format.
|
||||
.. figure:: ../../_figures/mixer/format-bump.png
|
||||
:alt: Format bump
|
||||
|
||||
The format version is incremented only when a compatibility breakage is
|
||||
introduced. Normal updates, such as updating a software package, do not require a format increment.
|
||||
Figure 1: Format bump
|
||||
|
||||
.. note::
|
||||
if you update to build 20 and then check which format of the distro is
|
||||
used, the new build version will show 30, and the new format will show 28.
|
||||
|
||||
.. rst-class:: content-collapse
|
||||
|
||||
@@ -840,8 +1093,9 @@ Set up a nginx web server for mixer with the following steps:
|
||||
|
||||
sudo systemctl start nginx
|
||||
|
||||
#. Verify the web server is running at \http://localhost. At this point
|
||||
you should no longer see a "404 Not Found" message.
|
||||
#. Verify the web server is running at \http://<ip-address>,
|
||||
where <ip-address> is the same one that you captured in
|
||||
`Example 1: Mix set up`_.
|
||||
|
||||
Related topics
|
||||
**************
|
||||
@@ -856,3 +1110,6 @@ Related topics
|
||||
.. _mixer.bundle man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.bundle.1.rst
|
||||
.. _mixer.build man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.build.1.rst
|
||||
.. _releases: https://github.com/clearlinux/clr-bundles/releases
|
||||
.. _afb.sh reference script: https://github.com/clearlinux/mixer-tools/blob/master/afb.sh
|
||||
|
||||
.. _ister: https://github.com/bryteise/ister
|
||||
@@ -133,6 +133,7 @@ Additional information
|
||||
**********************
|
||||
|
||||
* `stateless man page`_
|
||||
* :ref:`firmware`
|
||||
|
||||
.. _`stateless man page`: https://github.com/clearlinux/clr-man-pages/blob/master/stateless.7.rst
|
||||
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
.. _firmware:
|
||||
|
||||
Firmware
|
||||
########
|
||||
|
||||
This guide shows how |CL-ATTR| handles firmware and microcode loading.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Many devices and system components require firmware or microcode, software
|
||||
that runs directly on the device, to function correctly. Because firmware
|
||||
loading requires privileged hardware access, the kernel is involved in the
|
||||
process.
|
||||
|
||||
Firmware does not typically come with source code. Instead, firmware is
|
||||
provided as binary blobs which are licensed for free or non-free use.
|
||||
|
||||
In |CL| firmware is loaded during device initialization which typically
|
||||
happens at boot time.
|
||||
|
||||
|
||||
Included firmware
|
||||
*****************
|
||||
|
||||
The Linux kernel project contains a repository for firmware binaries that are
|
||||
licensed to allow free redistribution. |CL| packages these firmware binaries
|
||||
in the `linux-firmware bundles
|
||||
<https://clearlinux.org/software?search_api_fulltext=linux-firmware>`_ and
|
||||
automatically includes them with the kernel.
|
||||
|
||||
The Linux kernel's firmware repository can be found here:
|
||||
https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
|
||||
|
||||
If the firmware for your device is included upstream, no action is required
|
||||
for it to be automatically detected and loaded.
|
||||
|
||||
|
||||
Additional firmware loading
|
||||
***************************
|
||||
|
||||
Some device hardware manufacturers have a license that limits redistribution
|
||||
of firmware. This means |CL| is unable to distribute those firmware and you
|
||||
must manually obtain them from the manufacturer or another source.
|
||||
|
||||
You can place additional firmware in :file:`/etc/firmware`. |CL| reads this
|
||||
directory for additional firmware files in conjunction with the typical
|
||||
:file:`/lib/firmware` path to provide a :ref:`stateless design <stateless>`.
|
||||
|
||||
|
||||
#. Create the :file:`/etc/firmware` directory
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir -p /etc/firmware
|
||||
|
||||
#. Obtain the additional firmware binary from a trusted source.
|
||||
|
||||
#. Copy the firmware files including any subdirectories to
|
||||
:file:`/etc/firmware`. It is important to place the firmware files in
|
||||
expected path for proper loading.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo cp -Rv <directory>/<filename>.<fw|bin> /etc/firmware
|
||||
|
||||
|
||||
CPU microcode loading
|
||||
*********************
|
||||
|
||||
Microcode is low level code for processors loaded during the boot process that
|
||||
contain stability and security updates.
|
||||
|
||||
Microcode updates can be updated by motherboard firmware however this is not
|
||||
always feasible or does not happen in a timely fashion. The `Linux microcode
|
||||
loader`_ included in the Linux kernel allows for more flexibility and more
|
||||
frequent updates.
|
||||
|
||||
|CL| uses the *early loading* mechanism described in the `Linux microcode
|
||||
loader`_ documented by which the CPU microcode is loaded as early as possible
|
||||
in the boot process by using an initial RAM disk (initrd).
|
||||
|
||||
|
||||
Troubleshooting
|
||||
***************
|
||||
|
||||
Look at the output of :command:`sudo dmesg` to see device initialization and
|
||||
expected firmware paths
|
||||
|
||||
|
||||
|
||||
.. _`Linux microcode loader`: https://www.kernel.org/doc/Documentation/x86/microcode.txt
|
||||
@@ -0,0 +1,469 @@
|
||||
.. _container-image-modify:
|
||||
|
||||
Modify a |CL|-based container image
|
||||
###################################
|
||||
|
||||
This guide describes how to customize |CL-ATTR|-based container
|
||||
`images on Docker Hub`_, which include popular applications and runtimes.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Most of these images utilize a Docker build feature called a `multi-stage
|
||||
build to reduce image size`_ while some use single-stage build Dockerfiles. An
|
||||
official base `clearlinux image on Docker Hub`_ is also available. To create a
|
||||
generic |CL| container image, see :ref:`our guide <container-image-new>`.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
* Set up a functional Docker environment as described in :ref:`docker`.
|
||||
|
||||
* Download the |CL| microservice Dockerfile repo with the following
|
||||
command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/clearlinux/dockerfiles.git
|
||||
|
||||
* Navigate to and operate from the cloned :file:`dockerfiles` directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd dockerfiles/
|
||||
|
||||
|
||||
Example 1: Add a bundle
|
||||
***********************
|
||||
|
||||
In this example, we add :command:`wget` to the **clearlinux/redis**
|
||||
Dockerfile.
|
||||
|
||||
#. Enter :command:`swupd search wget` to discover which |CL| bundle includes
|
||||
the software. The output should tell you that :command:`wget` is available
|
||||
in the *wget* bundle.
|
||||
|
||||
#. Open a an editor to modify the Dockerfile.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$EDITOR redis/Dockerfile
|
||||
|
||||
#. Append the :command:`wget` bundle to the :command:`--bundles=` parameter
|
||||
of the :command:`swupd os-install` command.
|
||||
|
||||
#. Run :command:`git diff`.
|
||||
|
||||
The output shows the edits made after adding :command:`wget` in the
|
||||
clearlinux/redis Dockerfile.
|
||||
|
||||
.. code-block:: diff
|
||||
|
||||
diff --git a/redis/Dockerfile b/redis/Dockerfile
|
||||
index af977cb..b1effab 100644
|
||||
--- a/redis/Dockerfile
|
||||
+++ b/redis/Dockerfile
|
||||
@@ -15,7 +15,7 @@ RUN source /os-release && \
|
||||
mkdir /install_root \
|
||||
&& swupd os-install -V ${VERSION_ID} \
|
||||
--path /install_root --statedir /swupd-state \
|
||||
- --bundles=redis-native,findutils,su-exec --no-boot-update
|
||||
+ --bundles=redis-native,findutils,su-exec,wget --no-boot-update
|
||||
|
||||
#. Build the Dockerfile and apply a unique tag name. In this this example,
|
||||
we use :command:`wget_added` and add proxies.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build \
|
||||
--no-cache \
|
||||
--build-arg http_proxy=$http_proxy \
|
||||
--build-arg https_proxy=$https_proxy \
|
||||
--tag clearlinux/redis:wget_added \
|
||||
redis/
|
||||
|
||||
#. Run the Dockerfile with the `wget --version` command to verify that
|
||||
:command:`wget` has been added to the image.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run clearlinux/redis:wget_added wget --version
|
||||
|
||||
#. The output shows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
GNU Wget 1.20.3 built on linux-gnu.
|
||||
|
||||
-cares +digest -gpgme +https +ipv6 -iri +large-file -metalink +nls
|
||||
-ntlm +opie -psl +ssl/openssl
|
||||
|
||||
Example 2: Change |CL| version (single-stage build)
|
||||
***************************************************
|
||||
|
||||
This example shows how to rebuild single-stage containers against a specific
|
||||
OS version, :file:`<CL_VERSION>`, by adding a new argument to the Docker build
|
||||
command line.
|
||||
|
||||
#. Rebuild the :file:`clearlinux/machine-learning-ui`. Add an extra build
|
||||
argument :command:`swupd_args="-m <CL_VERSION>"`; in this case, the build
|
||||
version is 31110.
|
||||
|
||||
.. code-block:: bash
|
||||
:linenos:
|
||||
:emphasize-lines: 5
|
||||
|
||||
docker build \
|
||||
--no-cache \
|
||||
--build-arg http_proxy=$http_proxy \
|
||||
--build-arg https_proxy=$https_proxy \
|
||||
--build-arg swupd_args="-m 31110" \
|
||||
--tag clearlinux/machine-learning-ui:31110 \
|
||||
machine-learning-ui/
|
||||
|
||||
#. Run the docker container image:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run clearlinux/machine-learning-ui:31110 swupd info
|
||||
|
||||
#. Sample output shows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
Distribution: Clear Linux OS
|
||||
Installed version: 31110
|
||||
Version URL: https://cdn.download.clearlinux.org/update
|
||||
Content URL: https://cdn.download.clearlinux.org/update
|
||||
|
||||
|
||||
Example 3: Change |CL| version (multi-stage build)
|
||||
**************************************************
|
||||
|
||||
This example shows how to rebuild the cgit Dockerfile to use a specific |CL|
|
||||
version. The clearlinux/cgit Dockerfile has a multi-stage build with multiple
|
||||
layers: *os-core*, *httpd*, and *cgit*. This can be used as reference for
|
||||
building other multi-stage images with any number of layers.
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
All upper layers of multi-stage Dockerfiles inherit the |CL| version from
|
||||
the base layer. Rebuild the all underlying base layers against the desired
|
||||
OS version. In this example, four base layers must be rebuilt.
|
||||
|
||||
|
||||
First layer: os-core
|
||||
--------------------
|
||||
|
||||
#. Rebuild the first layer, *os-core*. Add an extra build argument
|
||||
:command:`swupd_args="-m <CL_VERSION>"`; in this case, the build
|
||||
version is 31110.
|
||||
|
||||
.. code-block:: bash
|
||||
:linenos:
|
||||
:emphasize-lines: 5
|
||||
|
||||
docker build \
|
||||
--no-cache \
|
||||
--build-arg http_proxy=$http_proxy \
|
||||
--build-arg https_proxy=$https_proxy \
|
||||
--build-arg swupd_args="-m 31110" \
|
||||
--tag clearlinux/os-core:31110 \
|
||||
os-core/
|
||||
|
||||
#. Verify the version-specific image is available:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker images clearlinux/os-core:31110
|
||||
|
||||
|
||||
Second layer: httpd
|
||||
-------------------
|
||||
|
||||
The next layer is :file:`clearlinux/httpd`.
|
||||
|
||||
#. Change the :file:`httpd/Dockerfile` to use the version-specific
|
||||
*os-core:31110* image that was previously built.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$EDITOR httpd/Dockerfile
|
||||
|
||||
#. Run :command:`git diff`.
|
||||
|
||||
The output shows a diff of a modified :file:`clearlinux/httpd` Dockerfile
|
||||
that uses the previously built clearlinux/os-core:31110.
|
||||
|
||||
.. code-block:: diff
|
||||
|
||||
diff --git a/httpd/Dockerfile b/httpd/Dockerfile
|
||||
index 6b2a6bf..9df89e4 100644
|
||||
--- a/httpd/Dockerfile
|
||||
+++ b/httpd/Dockerfile
|
||||
@@ -7,7 +7,7 @@ RUN swupd update --no-boot-update $swupd_args
|
||||
|
||||
# Grab os-release info from the minimal base image so
|
||||
# that the new content matches the exact OS version
|
||||
-COPY --from=clearlinux/os-core:latest /usr/lib/os-release /
|
||||
+COPY --from=clearlinux/os-core:31110 /usr/lib/os-release /
|
||||
|
||||
# Install additional content in a target directory
|
||||
# using the os version from the minimal base
|
||||
@@ -26,7 +26,7 @@ COPY --from=clearlinux/os-core:latest / /
|
||||
os_core_install/
|
||||
RUN cd / && \
|
||||
find os_core_install | sed -e 's/os_core_install/install_root/' | xargs rm -d &> /dev/null || true
|
||||
|
||||
-FROM clearlinux/os-core:latest
|
||||
+FROM clearlinux/os-core:31110
|
||||
|
||||
#. Build Dockerfile.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build \
|
||||
--no-cache \
|
||||
--build-arg http_proxy=$http_proxy \
|
||||
--build-arg https_proxy=$https_proxy \
|
||||
--tag clearlinux/httpd:31110 \
|
||||
httpd/
|
||||
|
||||
Third layer: cgit
|
||||
-----------------
|
||||
|
||||
The next layer is :file:`clearlinux/cgit`.
|
||||
|
||||
#. Change the :file:`cgit/Dockerfile` to use the desired OS
|
||||
version; in this case, the build version is 31110.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$EDITOR cgit/Dockerfile
|
||||
|
||||
#. Run :command:`git diff`.
|
||||
|
||||
The output shows:
|
||||
|
||||
.. code-block:: diff
|
||||
|
||||
diff --git a/cgit/Dockerfile b/cgit/Dockerfile
|
||||
index 9a3796d..59260fe 100644
|
||||
--- a/cgit/Dockerfile
|
||||
+++ b/cgit/Dockerfile
|
||||
@@ -7,7 +7,7 @@ RUN swupd update --no-boot-update $swupd_args
|
||||
|
||||
# Grab os-release info from the minimal base image so
|
||||
# that the new content matches the exact OS version
|
||||
-COPY --from=clearlinux/httpd:latest /usr/lib/os-release /
|
||||
+COPY --from=clearlinux/httpd:31110 /usr/lib/os-release /
|
||||
|
||||
# Install additional content in a target directory
|
||||
# using the os version from the minimal base
|
||||
@@ -22,11 +22,11 @@ RUN source /os-release && \
|
||||
# file exists on different layers. To minimize docker
|
||||
# image size, remove the overlapped files before copy.
|
||||
RUN mkdir /os_core_install
|
||||
-COPY --from=clearlinux/httpd:latest / /os_core_install/
|
||||
+COPY --from=clearlinux/httpd:31110 / /os_core_install/
|
||||
RUN cd / && \
|
||||
find os_core_install | sed -e 's/os_core_install/install_root/' | xargs rm -d &> /dev/null || true
|
||||
|
||||
-FROM clearlinux/httpd:latest
|
||||
+FROM clearlinux/httpd:31110
|
||||
|
||||
#. Build Dockerfile.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build \
|
||||
--no-cache \
|
||||
--build-arg http_proxy=$http_proxy \
|
||||
--build-arg https_proxy=$https_proxy \
|
||||
--tag clearlinux/cgit:31110 \
|
||||
cgit/
|
||||
|
||||
#. Verify the installed OS version by noting the :command:`VERSION_ID` value
|
||||
in the :file:`/usr/lib/os-release` file in the container filesystem.
|
||||
|
||||
.. code-block:: bash
|
||||
:linenos:
|
||||
:emphasize-lines: 6
|
||||
|
||||
docker run clearlinux/cgit:31110 cat /usr/lib/os-release
|
||||
NAME="Clear Linux OS"
|
||||
VERSION=1
|
||||
ID=clear-linux-os
|
||||
ID_LIKE=clear-linux-os
|
||||
VERSION_ID=31110
|
||||
PRETTY_NAME="Clear Linux OS"
|
||||
ANSI_COLOR="1;35"
|
||||
HOME_URL="https://clearlinux.org"
|
||||
SUPPORT_URL="https://clearlinux.org"
|
||||
BUG_REPORT_URL="mailto:dev@lists.clearlinux.org"
|
||||
PRIVACY_POLICY_URL=http://www.intel.com/privacy
|
||||
|
||||
|
||||
Example 4: Customize an application image at runtime
|
||||
****************************************************
|
||||
|
||||
This section describes how to modify a published |CL| container at runtime.
|
||||
In this example, we add Tensorflow\* into a :command:`clearlinux/python`
|
||||
container. This approach can help accelerate the feature development process.
|
||||
|
||||
In this example, three separate console windows are used to easily interact
|
||||
inside and outside of the container.
|
||||
|
||||
First console: Start the container
|
||||
----------------------------------
|
||||
|
||||
#. Launch the clearlinux/python container.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run -it --rm clearlinux/python
|
||||
Python 3.7.3 (default, Jun 17 2019, 00:47:04)
|
||||
[GCC 9.1.1 20190616 gcc-9-branch@272336] on linux
|
||||
Type "help", "copyright", "credits" or "license" for more information.
|
||||
|
||||
#. Try to import Tensorflow inside the container using the command:
|
||||
:command:`import tensorflow as tf`. The example below shows the expected
|
||||
error message because the Docker image does not yet include the Tensorflow
|
||||
module.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
>>> import tensorflow as tf
|
||||
Traceback (most recent call last):
|
||||
File "<stdin>", line 1, in <module>
|
||||
ModuleNotFoundError: No module named 'tensorflow'
|
||||
>>>
|
||||
|
||||
Second console: Add a bundle
|
||||
----------------------------
|
||||
|
||||
#. In another console, find the :command:`<Container_ID>` of
|
||||
clearlinux/python launched. This example Container ID is d4ce9d526fa6.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker ps
|
||||
|
||||
#. The output shows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
d4ce9d526fa6 clearlinux/python python3 About a minute ago Up About a minute amazing_villani
|
||||
|
||||
#. Connect to the running clearlinux/python container.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker exec -it d4ce9d526fa6 /usr/bin/bash
|
||||
root@d4ce9d526fa6/ #
|
||||
|
||||
|
||||
#. Use :command:`swupd` to install the machine-learning-tensorflow bundle.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
root@d4ce9d526fa6/ # swupd bundle-add machine-learning-tensorflow
|
||||
Loading required manifests...
|
||||
Downloading packs (692.32 Mb) for:
|
||||
- machine-learning-tensorflow
|
||||
… …
|
||||
...100%
|
||||
Finishing packs extraction...
|
||||
No extra files need to be downloaded
|
||||
Installing bundle(s) files...
|
||||
...100%
|
||||
Calling post-update helper scripts.
|
||||
Successfully installed 1 bundle
|
||||
|
||||
#. After the machine-learning-tensorflow bundle is installed in the
|
||||
container, in the first console, import Tensorflow, which will be
|
||||
successful now. You could also save the updated container using the
|
||||
command :command:`docker commit <Container_ID>`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
>>> import tensorflow as tf
|
||||
>>> tf.__version__
|
||||
'1.13.1'
|
||||
|
||||
Third console: Save the modified container
|
||||
------------------------------------------
|
||||
|
||||
#. In a third console, save the container with a new tag. Our example uses
|
||||
the tag `tensorflow_added` to identify our modified container.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker commit d4ce9d526fa6 clearlinux/python:tensorflow_added
|
||||
|
||||
#. Launch the modified container, and then import Tensorflow with success.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run -it clearlinux/python:tensorflow_added
|
||||
Python 3.7.3 (default, Jun 17 2019, 00:47:04)
|
||||
[GCC 9.1.1 20190616 gcc-9-branch@272336] on linux
|
||||
Type "help", "copyright", "credits" or "license" for more information.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
>>> import tensorflow as tf
|
||||
>>> tf.__version__
|
||||
'1.13.1'
|
||||
>>>
|
||||
|
||||
Background
|
||||
**********
|
||||
|
||||
Multi-stage Dockerfiles contain more than one :command:`FROM` directive. All
|
||||
of the multi-stage Clear Linux OS Dockerfiles share a common base layer
|
||||
called :command:`clearlinux/os-core:latest`. All of the higher level layers
|
||||
inherit the Clear Linux OS version from this base layer.
|
||||
|
||||
For details on how we leveraged multi-stage Docker builds, see the article
|
||||
`Minimizing Clear Linux OS container sizes`_.
|
||||
|
||||
#. :command:`clearlinux/os-core` is built once per day. It is a container
|
||||
containing a minimal Linux userspace.
|
||||
|
||||
#. The target container image uses either :command:`clearlinux/os-core` as a
|
||||
base layer or another container image :command:`clearlinux/` as a base
|
||||
layer.
|
||||
|
||||
#. Bundle(s) containing the application are downloaded during the first stage
|
||||
of the build process using :command:`swupd`.
|
||||
|
||||
#. The final container image is a composition of its base layer and the
|
||||
specific feature layer, via :command:`FROM clearlinux/<base layer>:latest
|
||||
, such as: os-core, httpd, and via :command:`COPY --from=builder /
|
||||
install_root /`. Using this method, the target container images are kept
|
||||
up to date without file duplication. For application-centric containers,
|
||||
`os-core-update` is excluded to improve size optimization.
|
||||
|
||||
Related topics
|
||||
**************
|
||||
|
||||
* :ref:`docker`
|
||||
* :ref:`container-image-new`
|
||||
|
||||
.. _images on Docker Hub: https://hub.docker.com/u/clearlinux
|
||||
.. _GitHub\*: https://github.com/clearlinux/dockerfiles
|
||||
.. _clearlinux image on Docker Hub: https://hub.docker.com/_/clearlinux
|
||||
.. _clearlinux microservice dockerfile repo: https://github.com/clearlinux/dockerfiles
|
||||
|
||||
.. _multi-stage build: https://docs.docker.com/develop/develop-images/multistage-build/
|
||||
|
||||
.. _Minimizing Clear Linux OS container sizes: https://clearlinux.org/blogs-news/minimizing-clear-linux-os-container-sizes
|
||||
|
||||
.. _multi-stage build to reduce image size: https://clearlinux.org/blogs-news/minimizing-clear-linux-os-container-sizes
|
||||
+8
-11
@@ -1,11 +1,11 @@
|
||||
.. _custom-clear-container:
|
||||
.. _container-image-new:
|
||||
|
||||
Build a custom |CL-ATTR| based Docker container image
|
||||
#######################################################
|
||||
Build a new |CL|-based container image
|
||||
######################################
|
||||
|
||||
This guide contains the steps to build a custom container image. The official
|
||||
base |CL-ATTR| container image is published on Docker\* Hub and is updated on
|
||||
a regular basis.
|
||||
This guide describes how to build a new |CL-ATTR|-based container image. The
|
||||
official base |CL-ATTR| container image is published on Docker\* Hub and is
|
||||
updated on a regular basis.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
@@ -90,16 +90,14 @@ Build the base container image
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update --version 29790 -B os-core-update,editors,network-basic base
|
||||
swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update -B os-core-update,editors,network-basic base
|
||||
|
||||
|
||||
The swupd example uses the following flags:
|
||||
|
||||
* :command:`os-install` tells swupd to download and install.
|
||||
* :command:`-V / --version` specifies the version of the |CL| bundles.
|
||||
* :command:`--url` specifies the URL of the bundles repository.
|
||||
* :command:`--statedir` specifies the state directory where downloaded bundles
|
||||
and any state information are stored.
|
||||
* :command:`--statedir` specifies the state directory where downloaded bundles and any state information are stored.
|
||||
* :command:`--no-boot-update` tells swupd to skip updating boot files because
|
||||
boot files are not required for a container.
|
||||
|
||||
@@ -324,4 +322,3 @@ Example output:
|
||||
Removing intermediate container 7694989e97de
|
||||
Successfully built ec23189ef954
|
||||
Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest
|
||||
|
||||
@@ -32,13 +32,13 @@ This example uses the following DPDK components:
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
* Two platforms using |CL-ATTR| release `13330`_ or higher.
|
||||
* Two platforms using |CL-ATTR| release `31130`_ or higher.
|
||||
* Both images must include the :command:`kernel-native` bundle.
|
||||
* Install the :command:`network-basic-dev` bundle with the command:
|
||||
* Install the following packages:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add network-basic-dev
|
||||
sudo swupd bundle-add network-basic-dev dpdk devpkg-dpdk
|
||||
|
||||
* Each platform must have at least one :abbr:`NIC (Network Interface Card)`.
|
||||
Check the `DPDK project`_ for the list of supported `dpdk.org NICs`_.
|
||||
@@ -65,14 +65,14 @@ Install dpdk and build l3fwd example (Platform B)
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo export RTE_TARGET=x86_64-native-linuxapp-gcc
|
||||
sudo export RTE_TARGET=x86_64-native-linux-gcc
|
||||
|
||||
#. Build the `l3fwd` application and add the configuration header to
|
||||
the :makevar:`CFLAGS` variable.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo make CFLAGS+="-include /usr/include/rte_config.h"
|
||||
sudo make
|
||||
|
||||
|
||||
Build pktgen (Platform A)
|
||||
@@ -92,7 +92,7 @@ Build pktgen (Platform A)
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo export RTE_TARGET=x86_64-native-linuxapp-gcc
|
||||
sudo export RTE_TARGET=x86_64-native-linux-gcc
|
||||
|
||||
#. Build the `pktgen` project and set the :makevar:`CONFIG_RTE_BUILD_SHARED_LIB` variable
|
||||
to "n".
|
||||
@@ -144,14 +144,14 @@ packet buffers.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
|
||||
echo 1024 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
|
||||
|
||||
#. Allocate pages on NUMA machines.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
|
||||
sudo echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages
|
||||
echo 1024 | sudo tee /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
|
||||
echo 1024 | sudo tee /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages
|
||||
|
||||
#. Make memory available for DPDK.
|
||||
|
||||
@@ -224,7 +224,7 @@ Run pktgen application (Platform A)
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ./app/app/x86_64-native-linuxapp-gcc/pktgen -c 0xf -n 4 -- -p 0xf -P -m "1.0, 2.1"
|
||||
sudo ./app/app/x86_64-native-linux-gcc/pktgen -c 0xf -n 4 -- -p 0xf -P -m "1.0, 2.1"
|
||||
|
||||
#. Enable active colorful output (optional).
|
||||
|
||||
@@ -302,10 +302,10 @@ machines control the NICs on the host.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo echo "8086 1521" > /sys/bus/pci/drivers/pci-stub/new_id
|
||||
sudo echo "0000:03:00.0" > /sys/bus/pci/drivers/igb/unbind
|
||||
sudo echo "0000:03:00.0" > /sys/bus/pci/drivers/pci-stub/bind
|
||||
sudo echo "8086 1521" > /sys/bus/pci/drivers/pci-stub/remove_id
|
||||
echo "8086 1521" | sudo tee /sys/bus/pci/drivers/pci-stub/new_id
|
||||
echo "0000:03:00.0" | sudo tee /sys/bus/pci/drivers/igb/unbind
|
||||
echo "0000:03:00.0" | sudo tee /sys/bus/pci/drivers/pci-stub/bind
|
||||
echo "8086 1521" | sudo tee /sys/bus/pci/drivers/pci-stub/remove_id
|
||||
|
||||
#. Assign the unbound NICs to the KVM virtual machine (guest).
|
||||
Modify the :file:`start_qemu.sh` script in `qemu-system-x86_64` arguments, and
|
||||
@@ -343,7 +343,7 @@ machines control the NICs on the host.
|
||||
#. Run the :file:`start_qemu.sh` script.
|
||||
|
||||
|
||||
.. _13330: https://cdn.download.clearlinux.org/releases/13330/
|
||||
.. _31130: https://cdn.download.clearlinux.org/releases/31130/clear/
|
||||
.. _DPDK project: http://dpdk.org
|
||||
.. _dpdk.org NICs: http://dpdk.org/doc/nics
|
||||
.. _pktgen tar package: http://dpdk.org/browse/apps/pktgen-dpdk/refs
|
||||
|
||||
@@ -0,0 +1,201 @@
|
||||
.. _firewall:
|
||||
|
||||
Firewall
|
||||
#########
|
||||
|
||||
Firewalls control access to and from systems based on network packet
|
||||
attributes like IP address, port, payload and more.
|
||||
|
||||
The `Netfilter <https://netfilter.org/>`_ framework in the Linux kernel
|
||||
performs packet filtering and provides the means for implementing a software
|
||||
firewall in Linux. |CL-ATTR| has a couple different firewall front-end options
|
||||
for managing the Linux firewall.
|
||||
|
||||
|
||||
.. contents:: :local:
|
||||
:depth: 2
|
||||
|
||||
|
||||
Default ruleset
|
||||
***************
|
||||
|
||||
|CL| does not impose a firewall policy out of the box. All traffic is allowed
|
||||
inbound and all traffic is allowed outbound. However, `tallow`_ is installed
|
||||
by default and may dynamically create a rule temporarily restricting access
|
||||
from external hosts.
|
||||
|
||||
.. warning::
|
||||
|
||||
Changing firewall configuration can cause abrupt network disconnection. If
|
||||
this happens on a remote host, local recovery may be required.
|
||||
|
||||
Be sure to test your firewall configuration before committing it
|
||||
permanently to ensure your system will remain accessible remotely, if
|
||||
required.
|
||||
|
||||
Firewall software
|
||||
*****************
|
||||
|
||||
iptables
|
||||
========
|
||||
|
||||
:command:`iptables` is a well-known user-space administration tool for
|
||||
configuring IPv4 Linux firewall rules. :command:`ip6tables` is the
|
||||
complimentary tool for configuring IPv6 Linux firewall rules.
|
||||
|
||||
Below is information on using :command:`iptables` on |CL|:
|
||||
|
||||
#. Make sure the *iptables* bundle is installed
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo swupd bundle-add iptables
|
||||
|
||||
|
||||
#. Define new iptables rules/chains for the running configuration using the
|
||||
:command:`iptables` command. See :command:`man iptables` for iptables
|
||||
concepts and configuration options.
|
||||
|
||||
Below is a common restrictive firewall configuration which denies all
|
||||
incoming connections, unless the connection was initiated by the host.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
# Set default chain policies
|
||||
sudo iptables -P INPUT DROP
|
||||
sudo iptables -P FORWARD DROP
|
||||
sudo iptables -P OUTPUT ACCEPT
|
||||
|
||||
# Accept on localhost loopback device
|
||||
sudo iptables -A INPUT -i lo -j ACCEPT
|
||||
sudo iptables -A OUTPUT -o lo -j ACCEPT
|
||||
|
||||
# Allow established sessions to receive traffic
|
||||
sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
|
||||
|
||||
|
||||
#. Test the running firewall configuration to make sure it behaving as
|
||||
you expect.
|
||||
|
||||
#. Run the *iptables-save* service to make the running configuration
|
||||
persistent. This will perform a one-time save of the running configuration
|
||||
to :file:`/etc/iptables.rules` :
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo systemctl start iptables-save
|
||||
|
||||
#. Enable the *iptables-resolve* service the iptables rules to be
|
||||
automatically applied at boot from the :file:`/etc/iptables.rules` file:
|
||||
|
||||
.. code :: bash
|
||||
|
||||
sudo systemctl enable iptables-restore.service
|
||||
|
||||
|
||||
ipset
|
||||
=====
|
||||
|
||||
`ipset <http://ipset.netfilter.org/>`_ is a framework in the Linux kernel for
|
||||
storing and efficiently indexing combinations of IP addresses, networks,
|
||||
(TCP/UDP) port numbers, MAC addresses, and interface names.
|
||||
|
||||
IP sets makes writing network policy rules simpler and processing them against
|
||||
a large and/or changing sets of hosts more efficient.
|
||||
|
||||
By themselves, IP sets do not enforce network traffic rules but can be used to
|
||||
extend iptables rules for matching. It is important to note that the ipset
|
||||
must be defined before a netfilter rule can match against it.
|
||||
|
||||
* Running IP sets can be manipulated with the :command:`ipset` utility.
|
||||
|
||||
* Custom IP sets can be stored in the :file:`/etc/ipset.conf` file
|
||||
|
||||
* IP sets in :file:`/etc/ipset.conf` can be automatically applied at boot by
|
||||
enabling the *ipset* service with the command :command:`sudo systemctl
|
||||
enable ipset`.
|
||||
|
||||
See :command:`man ipset` to learn more about using ipsets.
|
||||
|
||||
|
||||
firewalld
|
||||
=========
|
||||
|
||||
`firewalld <https://firewalld.org/>`_ is based on nftables, the successor to
|
||||
iptables and parts of the netfilter framework. The description of firewalld
|
||||
helps highlight some of the differences compared to iptables:
|
||||
|
||||
firewalld provides a dynamically managed firewall with support for
|
||||
network/firewall zones to define the trust level of network connections or
|
||||
interfaces. It has support for IPv4, IPv6 firewall settings and for
|
||||
ethernet bridges and has a separation of runtime and permanent
|
||||
configuration options. It also supports an interface for services or
|
||||
applications to add firewall rules directly.
|
||||
|
||||
See :command:`man firewalld` for more information.
|
||||
|
||||
Below is information on using :command:`firewalld` on |CL|:
|
||||
|
||||
#. Install he *firewalld* bundle:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo swupd bundle-add firewalld
|
||||
|
||||
|
||||
#. Disable *iptables* and *ipset* services as they conflict with firewalld:
|
||||
|
||||
.. code::
|
||||
|
||||
sudo systemctl mask iptables-restore ipset
|
||||
|
||||
|
||||
#. :command:`firewall-cmd` can be used to configure the running or permanent
|
||||
firewall configuration. See the `firewalld documentation
|
||||
<https://firewalld.org/documentation/>`_ to learn more about
|
||||
firewalld concepts and configuration options.
|
||||
|
||||
Below is a common example to allow HTTPS traffic in public zones:
|
||||
|
||||
.. code::
|
||||
|
||||
sudo firewall-cmd --permanent --zone=public --add-service=https
|
||||
|
||||
|
||||
#. Enable the *firewalld* service the so that the firewalld daemon is
|
||||
automatically started and rules applied at boot from the
|
||||
:file:`/etc/firewalld/*` file:
|
||||
|
||||
.. code :: bash
|
||||
|
||||
sudo systemctl enable --now firewalld.service
|
||||
|
||||
|
||||
#. Verify that firewalld is running:
|
||||
|
||||
.. code :: bash
|
||||
|
||||
sudo firewall-cmd --state
|
||||
|
||||
|
||||
|
||||
Troubleshooting
|
||||
***************
|
||||
|
||||
When troubleshooting connectivity issues that may be related to firewall
|
||||
rules.
|
||||
|
||||
* Consider restrictions at the physical network level.
|
||||
|
||||
* For inbound connections, make sure your application is listening on the
|
||||
network port you're expecting with :command:`lsof` or :command:`netstat`.
|
||||
|
||||
* For outbound connections, make sure the destination host is responding to
|
||||
the network port you're expecting with :command:`nc`. If the connection is
|
||||
refused, then there may be a problem with the destination server.
|
||||
|
||||
* If you're using firewalld, check the daemon status with the command:
|
||||
:command:`systemctl status firewalld`.
|
||||
|
||||
|
||||
.. _`tallow`: https://github.com/clearlinux/tallow
|
||||
+114
-46
@@ -6,25 +6,26 @@ Data Analytics Reference Stack
|
||||
This guide explains how to use the :abbr:`DARS (Data Analytics Reference Stack)`,
|
||||
and to optionally build your own DARS container image.
|
||||
|
||||
Any system that supports Docker\* containers can be used with DARS. This steps
|
||||
Any system that supports Docker\* containers can be used with DARS. The steps
|
||||
in this guide use |CL-ATTR| as the host system.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
The Data Analytics Reference Stack release
|
||||
******************************************
|
||||
Overview
|
||||
********
|
||||
|
||||
The Data Analytics Reference Stack (DARS) provides developers and enterprises a straightforward, highly optimized software stack for storing and processing large
|
||||
amounts of data. More detail is available on the
|
||||
`DARS architecture and performance benchmarks`_.
|
||||
The Data Analytics Reference Stack (DARS) provides developers and enterprises a straightforward, highly optimized software stack for storing and processing large amounts of data. More detail is available on the `DARS architecture and performance benchmarks`_.
|
||||
|
||||
Stack Features
|
||||
==============
|
||||
|
||||
The Data Analytics Reference Stack provides two pre-built Docker images,
|
||||
available on `Docker Hub`_:
|
||||
|
||||
* A |CL|-derived `DARS with OpenBlas`_ stack optimized for `OpenBLAS`_
|
||||
* A |CL|-derived `DARS with Intel® MKL`_ stack optimized for `MKL`_
|
||||
* A |CL|-derived `DARS with Intel® MKL`_ stack optimized for `MKL`_ (Intel® Math Kernel Library)
|
||||
|
||||
We recommend you view the latest component versions for each image in the
|
||||
:file:`README` found in the `Data Analytics Reference Stack`_ GitHub\*
|
||||
@@ -41,78 +42,137 @@ in the |CL|-based containers may not be the latest released by |CL|.
|
||||
Using the Docker images
|
||||
***********************
|
||||
|
||||
#. To immediately start using the latest stable DARS images, pull an image
|
||||
Launching the Image
|
||||
===================
|
||||
|
||||
#. To use the latest stable DARS images, pull an image
|
||||
directly from `Docker Hub`_. This example uses the
|
||||
`DARS with Intel® MKL`_ Docker image.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker pull clearlinux/stacks-dars-mkl
|
||||
|
||||
|
||||
#. Once you have downloaded the image, you can run it with
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run -it --ulimit nofile=1000000:1000000 --name mkl <name of image>
|
||||
|
||||
This will launch the image and drop you into a bash shell inside the
|
||||
container. You will see output similar to the following:
|
||||
This will launch the image and drop you into a bash shell inside the container. The :command:`--ulimit nofile=` parameter is required in order to increase the allowed number of open files for the Apache Spark engine.
|
||||
|
||||
If you need to verify the name of the DARS image, you can use the :command:`docker image ls` command to see which images reside on your system.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker image ls
|
||||
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
root@fd5155b89857 /root # spark-shell
|
||||
spark-shell
|
||||
Config directory: /usr/share/defaults/spark/
|
||||
Welcome to
|
||||
____ __
|
||||
/ __/__ ___ _____/ /__
|
||||
_\ \/ _ \/ _ `/ __/ '_/
|
||||
/___/ .__/\_,_/_/ /_/\_\ version 2.4.0
|
||||
/_/
|
||||
REPOSITORY TAG IMAGE ID CREATED SIZE
|
||||
clearlinux/stacks-dars-mkl test-img 49a70a22231f 23 hours ago 2.66GB
|
||||
ubuntu latest 2ca708c1c9cc 7 days ago 64.2MB
|
||||
katadocker/kata-deploy latest bd6dc92f8060 7 days ago 673MB
|
||||
clearlinux/stacks-dars-mkl latest 2c9555536d5f 4 weeks ago 2.62GB
|
||||
|
||||
Using Scala version 2.12.7 (OpenJDK 64-Bit Server VM, Java 1.8.0-internal)
|
||||
Type in expressions to have them evaluated.
|
||||
Type :help for more information.
|
||||
|
||||
scala>
|
||||
|
||||
The :command:`--ulimit nofile` parameter is currently required in order to
|
||||
increase the number of open files opened at certain point by the spark
|
||||
engine.
|
||||
|
||||
Building DARS images
|
||||
********************
|
||||
====================
|
||||
|
||||
If you choose to build your own DARS container images, you can customize
|
||||
them as needed. Use the provided Dockerfile as a baseline.
|
||||
If you choose to build your own DARS container images, you can customize them as needed. Use the :file:`Dockerfile` included in the Github\* repository as your baseline.
|
||||
|
||||
To construct images with |CL|, start with a |CL| development platform that
|
||||
has the :command:`containers-basic-dev` bundle installed. Learn more about
|
||||
bundles and installing them by using :ref:`swupd-guide`.
|
||||
To construct images with |CL|, start with a |CL| development platform that has the :command:`containers-basic-dev` bundle installed. Learn more about bundles and installing them by using :ref:`swupd-guide`.
|
||||
|
||||
#. Clone the `Data Analytics Reference Stack`_ GitHub\* repository.
|
||||
#. The `Data Analytics Reference Stack`_ is part of the |CL| Project GitHub\* repository. Clone the :file:`dockerfiles` repository.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/clearlinux/dockerfiles/tree/master/stacks/dars -b master
|
||||
git clone https://github.com/clearlinux/dockerfiles.git
|
||||
|
||||
#. Inside the DARS directory, run :command:`make` to build OpenBLAS and MKL images.
|
||||
#. Inside the :file:`stacks/dars/mkl` directory, use docker with the :file:`Dockerfile` to build the MKL image.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make
|
||||
cd ./dockerfiles/stacks/dlrs/mkl
|
||||
docker build --no-cache -t clearlinux/stacks-dars-mkl .
|
||||
|
||||
Run :command:`make baseline` to build the baseline CentOS image. Depending on
|
||||
the system, it may take a while to finish building.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make baseline
|
||||
|
||||
#. Once completed, check the resulting images with :command:`Docker`
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker images | grep dars
|
||||
docker images | grep dars
|
||||
|
||||
#. You can use any of the resulting images to launch fully functional containers. If you need to customize the containers, you can edit the provided :file:`Dockerfile`.
|
||||
|
||||
Using Apache Spark\* in DARS
|
||||
****************************
|
||||
|
||||
After launching the container, you can start Apache Spark with either the Scala or PySpark environment. For these examples we will use PySpark, which is the Python\* API for Apache Spark.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pyspark
|
||||
|
||||
|
||||
Launching is as simple as this. Depending on your system configuration and capabilities, you may need to define proxy or memory allocation settings on the command line or in a config file for optimal performance. Refer to the `Apache Spark documentation`_ for more detail.
|
||||
|
||||
After executing :command:`pyspark`, you will see output similar to this.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
root@fd5155b89857 /root # pyspark
|
||||
Welcome to
|
||||
____ __
|
||||
/ __/__ ___ _____/ /__
|
||||
_\ \/ _ \/ _ `/ __/ '_/
|
||||
/__ / .__/\_,_/_/ /_/\_\ version 2.4.0
|
||||
/_/
|
||||
|
||||
Using Python version 3.7.4 (default, Jul 13 2019 06:59:17)
|
||||
SparkSession available as 'spark'.
|
||||
>>>
|
||||
|
||||
|
||||
Execute code directly in PySpark
|
||||
================================
|
||||
|
||||
A simple example for verifying that pyspark is working correctly is to run a small python function from a `PySpark getting started guide`_ to estimate the value of Pi. Run these lines in the PySpark shell.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
import random
|
||||
NUM_SAMPLES = 100000000
|
||||
def inside(p):
|
||||
x, y = random.random(), random.random()
|
||||
return x*x + y*y < 1
|
||||
|
||||
count = sc.parallelize(range(0, NUM_SAMPLES)).filter(inside).count()
|
||||
pi = 4 * count / NUM_SAMPLES
|
||||
print(“Pi is roughly”, pi)
|
||||
|
||||
|
||||
Run Python programs with spark-submit
|
||||
=====================================
|
||||
|
||||
You can also run python scripts in Apache Spark from the command line. We'll use the Apache Spark example found in the :file:`/usr/share/apache-spark/examples/src/main/python/pi.py` file. Note that we have turned off the INFO and WARN messages in Apache Spark for this example.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
#spark-submit /usr/share/apache-spark/examples/src/main/python/pi.py
|
||||
Config directory: /usr/share/defaults/spark/
|
||||
Pi is roughly 3.134700
|
||||
|
||||
DARS Usecase example
|
||||
====================
|
||||
|
||||
The DARS container is used in conjunction with the Deep Learning Reference Stack container to implement a real world use case. Refer to the `Github Issue Classification`_ Usecase found in the `stacks-usecase`_ repository for a walkthrough. This usecase is implemented using the Scala environment, rather than PySpark.
|
||||
|
||||
|
||||
|
||||
#. You can use any of the resulting images to launch fully functional containers.
|
||||
If you need to customize the containers, you can edit the provided :file:`Dockerfile`.
|
||||
|
||||
.. _Data Analytics Reference Stack: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dars
|
||||
|
||||
@@ -131,3 +191,11 @@ bundles and installing them by using :ref:`swupd-guide`.
|
||||
.. _DARS architecture and performance benchmarks: https://clearlinux.org/stacks/data-analytics-stack-v1
|
||||
|
||||
.. _DARS Terms of Use: https://clearlinux.org/stacks/data-analytics/terms-of-use
|
||||
|
||||
.. _PySpark getting started guide: https://towardsdatascience.com/how-to-get-started-with-pyspark-1adc142456ec
|
||||
|
||||
.. _Apache Spark documentation: https://spark.apache.org/docs/latest/
|
||||
|
||||
.. _stacks-usecase: https://github.com/intel/stacks-usecase
|
||||
|
||||
.. _Github Issue Classification: https://github.com/intel/stacks-usecase/tree/master/github-issue-classification
|
||||
|
||||
@@ -0,0 +1,635 @@
|
||||
.. _dbrs:
|
||||
|
||||
Database Reference Stack
|
||||
########################
|
||||
|
||||
This guide describes the hardware and installation requirements for using the
|
||||
:abbr:`DBRS (Database Reference Stack)`, along with getting started configuration examples, using |CL-ATTR| as the host system.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Database Reference Stack is integrated, highly-performant, open source,
|
||||
and optimized for 2nd generation Intel® Xeon® Scalable Processors and Intel®
|
||||
Optane™ DC Persistent Memory. This open source community release is part of
|
||||
an effort to ensure developers have easy access to the features and
|
||||
functionality of Intel Platforms.
|
||||
|
||||
Stack Features
|
||||
==============
|
||||
|
||||
Current supported database applications are Apache Cassandra* and Redis*, which
|
||||
have been enabled for `Intel Optane DC PMM`_.
|
||||
|
||||
DBRS with Apache Cassandra can be deployed as a standalone container or inside a
|
||||
Kubernetes* cluster.
|
||||
|
||||
The Redis stack application is enabled for a multinode Kubernetes
|
||||
environment, using AEP persistent memory DIMM in fsdax mode for storage.
|
||||
|
||||
The `release announcement`_ for this release provides more detail about the stack features, as well as benchmark results.
|
||||
|
||||
.. note::
|
||||
|
||||
The Database Reference Stack is a collective work, and each piece
|
||||
of software within the work has its own license. Please see the
|
||||
`DBRS Terms of Use`_ for more details about licensing and usage of the Database Reference Stack.
|
||||
|
||||
|
||||
Hardware Requirements
|
||||
*********************
|
||||
|
||||
* Intel Xeon Scalable Platform with Intel C620 chipset series
|
||||
* 2nd Gen Intel Xeon Scalable processor CPU (Intel Optane DC PMM-enabled stepping) Provides cache & memory control. Intel Optane DC persistent memory works only on systems powered by 2nd Generation Intel® Xeon® Platinum or Gold processors.
|
||||
* BIOS with Reference Code
|
||||
* Intel Optane DC persistent memory
|
||||
|
||||
Hardware configuration used in stacks development
|
||||
=================================================
|
||||
|
||||
* Intel® Server System R2208WFTZSR
|
||||
* BIOS with Reference Code
|
||||
* BIOS ID: SE5C620.86B.0D.01.0438.032620191658
|
||||
* BMC Firmware: 1.94.6b42b91d
|
||||
* Apache Pass Firmware: 1.2.0.5310
|
||||
* 2x Intel Xeon Platinum 8268 Processor
|
||||
* Intel SSD DC S5600 Series 960GB 2.5in SATA Drive
|
||||
* 64 GB RAM - Distributed in 4x 16 GB DDR4 DIMM's
|
||||
* 2x Intel Optane DC Persistent Memory 256GB Module
|
||||
* 1-1-1 Layout 8 Optane : 1 RAM ratio
|
||||
|
||||
|
||||
.. list-table:: **Table 1. IMC**
|
||||
:widths: 16,16,16,16,16,16
|
||||
:header-rows: 1
|
||||
|
||||
* - Channel 2
|
||||
- Channel 2
|
||||
- Channel 1
|
||||
- Channel 1
|
||||
- Channel 0
|
||||
- Channel 0
|
||||
|
||||
* - Slot 1
|
||||
- Slot 0
|
||||
- Slot 1
|
||||
- Slot 0
|
||||
- Slot 1
|
||||
- Slot 0
|
||||
|
||||
* -
|
||||
- 256 AEP
|
||||
-
|
||||
- 16 GB DRAM
|
||||
-
|
||||
- 16 GB DRAM
|
||||
|
||||
Firmware configuration
|
||||
**********************
|
||||
|
||||
.. important::
|
||||
|
||||
When updating DCPMM Firmware, all DCPMM parts must be in the same mode (you cannot mix 1LM and 2LM parts).
|
||||
|
||||
The latest firmware download for the Intel® Server System S2600WF Family is available at the `Intel Download Center`_
|
||||
|
||||
Firmware Update Steps
|
||||
=====================
|
||||
|
||||
#. Unzip the contents of the update package and copy all files to the root directory of a removable media (USB flash drive).
|
||||
#. Insert the USB flash drive to any available USB port on the system to be updated.
|
||||
#. Boot to EFI shell.
|
||||
#. Input "fsx(x:0,1,...):" to enter into your usb disk
|
||||
#. Run "startup.nsh"
|
||||
#. After update BMC firmware, system BIOS, ME firmware,FD, FRUSDR, system will reboot automatically.
|
||||
|
||||
|
||||
If Intel Optane DC Persistent Memory is installed, run startup.nsh a second time after the first reboot to upgrade Intel Optane DC Persistent Memory Firmware:
|
||||
|
||||
* Boot to EFI shell.
|
||||
* Input "fsx(x:0,1,...):" to enter into your usb disk
|
||||
* Run "startup.nsh" again to update the corresponding AEP FW.
|
||||
|
||||
|
||||
Hardware Configuration
|
||||
**********************
|
||||
|
||||
|
||||
Online Resources
|
||||
================
|
||||
|
||||
Before going through the configuration steps, we strongly recommend visiting the following resources and wikis to have a broader understanding of what is being done
|
||||
|
||||
* `Quick Start Guide`_ Configure Intel Optane DC Persistent Memory Modules on Linux
|
||||
* `Managing NVDIMMs`_
|
||||
* `Configure, Manage, and Profile`_ Intel Optane DC Persistent Memory Modules
|
||||
|
||||
Optane DIMM Configuration
|
||||
=========================
|
||||
|
||||
The persistent memory DIMMs can be configured in devdax or fsdax mode. The use case to enable database stack on a kubernetes environment currently only support fsdax mode.
|
||||
|
||||
Configuration Steps
|
||||
===================
|
||||
|
||||
.. important::
|
||||
|
||||
Run the following steps with root privileges (sudo) as shown in the examples
|
||||
|
||||
|
||||
#. To configure Optane DIMMs for App direct mode run this command and then reboot the system
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ipmctl create -goal PersistentMemoryType=AppDirect
|
||||
|
||||
|
||||
#. Next, list the pmem devices in the system
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ndctl list –N
|
||||
|
||||
|
||||
#. Create namespaces based on the regions and set mode as fsdax -- use the names of the regions listed in previous step as the –-region parameter
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ndctl create-namespace --region=region0 --mode=fsdax
|
||||
|
||||
|
||||
#. Create the filesystem and mount it. We are using /mnt/dax{#} as a convention in this guide to mount our devices
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkfs.ext4 /dev/pmem{n}
|
||||
sudo mount -o dax /dev/pmem0 /mnt/dax0
|
||||
|
||||
|
||||
Running DBRS with Apache Cassandra*
|
||||
***********************************
|
||||
|
||||
DBRS with Apache Cassandra can be deployed as a standalone container or inside
|
||||
Kubernetes\*. Instructions for both cases is included here. Note that you can
|
||||
use the released `Docker image with Apache Cassandra`_ (Docker\* examples below).
|
||||
These instructions provide a baseline for creating your own container image.
|
||||
If you are using the released image, skip this section.
|
||||
|
||||
.. important::
|
||||
|
||||
At the initial release of DBRS, Apache Cassandra is considered to be Engineering Preview release quality and may not be suitable for production release. Please take this into consideration when planning your project.
|
||||
|
||||
|
||||
|
||||
Build the DBRS with Apache Cassandra container
|
||||
==============================================
|
||||
|
||||
To build the container with Apache Cassandra, you must build cassandra-pmem, and then build the container using the :command:`docker build` command. We are using |CL| as our container host as well as the OS in the container.
|
||||
|
||||
Build cassandra-pmem
|
||||
====================
|
||||
|
||||
.. important::
|
||||
|
||||
At the initial release of DBRS, the pmem-csi driver is considered to be Engineering Preview release quality and may not be suitable for production release. Please take this into consideration when planning your project.
|
||||
|
||||
|
||||
In the `DBRS github repository`_, there is a file called `build-cassandra-pmem.sh`_, which handles all the requirements for compiling cassandra-pmem for Dockerfile usage. The dependencies for this build can be installed with :command:`swupd`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add c-basic java-basic devpkg-pmdk pmdk
|
||||
|
||||
|
||||
Once installed, we run the script
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
./build-cassandra-pmem.sh
|
||||
|
||||
|
||||
At the completion of the build you will have a file called :file:`cassandra-pmem-build.tar.gz`. Place this file in the same directory with the Dockerfile to build the Docker image.
|
||||
|
||||
Build the Docker container
|
||||
==========================
|
||||
|
||||
To build the Docker image, run the Dockerfile in the same directory with the :file:`cassandra-pmem-build.tar.gz`
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build --force-rm --no-cache -f Dockerfile -t $build_image_name .
|
||||
|
||||
|
||||
Once it completes, the Docker image is ready to be used.
|
||||
|
||||
Deploy Apache Cassandra PMEM as a standalone container
|
||||
======================================================
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
To deploy Apache Cassandra PMEM, you must meet the following requirements
|
||||
|
||||
* PMEM memory must be configured in `devdax` or `fsdax` mode. The container image is able to handle both modes and depending on the PMEM mode, the mount points inside the container must be different.
|
||||
* In order to make available `devdax` pmem devices inside the container you must use the `--device` directive. Internally the container always uses :command:`/dev/dax0.0`, so the mapping should be: :command:`--device=/dev/<host-device>:/dev/dax0.0`
|
||||
* In a similar fashion for `fsdax` we need the device to be mapped to :command:`/mnt/pmem` inside the container: :command:`--mount type=bind,source=<source-mount-point>,target=/mnt/pmem`
|
||||
|
||||
|
||||
Preparing PMEM for container use
|
||||
--------------------------------
|
||||
|
||||
The cassandra-pmem image is capable of using both `fsdax` and `devdax`, the necessary steps to configure the PMEM to work with cassandra are documented here.
|
||||
|
||||
fsdax
|
||||
-----
|
||||
|
||||
Verify that the PMEM is in `fsdax` mode
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ndctl list -u
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
{
|
||||
"dev":"namespace0.0",
|
||||
"mode":"fsdax",
|
||||
"map":"mem",
|
||||
"size":"4.00 GiB (4.29 GB)",
|
||||
"sector_size":512,
|
||||
"blockdev":"pmem0"
|
||||
}
|
||||
|
||||
|
||||
If for some reason the device is not in `fsdax` mode you can reconfigure the namespace as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo `ndctl create-namespace -fe <namespace-name> --mode=fsdax`
|
||||
|
||||
|
||||
Once the PMEM namespace is configured, you will see a device named :file:`/dev/pmem{0-9}`. We will create a filesystem on that device. The filesystem could be `ext4` or `xfs`, for this example we are going to use `ext4`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkfs.ext4 /dev/pmem0
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
mke2fs 1.45.2 (27-May-2019)
|
||||
Creating filesystem with 1031680 4k blocks and 258048 inodes
|
||||
Filesystem UUID: 303c03f5-ac4e-4462-8bf9-bc6b0fae53fe
|
||||
Superblock backups stored on blocks:
|
||||
32768, 98304, 163840, 229376, 294912, 819200, 884736
|
||||
|
||||
Allocating group tables: done
|
||||
Writing inode tables: done
|
||||
Creating journal (16384 blocks): done
|
||||
Writing superblocks and filesystem accounting information: done
|
||||
|
||||
|
||||
Once the filesystem is created, we mount it with the dax option
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mount /dev/pmem0 /mnt/pmem -o dax
|
||||
|
||||
|
||||
When using `fsdax` mode cassandra-pmem creates a pool file on the pmem mountpoint, so the `jvm.options` configuration should look like the output below:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
-Dpmem_path=/mnt/pmem/cassandra_pool
|
||||
-Dpool_size=3221225472
|
||||
|
||||
|
||||
|
||||
Where
|
||||
* `pmem_path` is the path to the pool file, which should include the path itself and the file name
|
||||
* `pool_size` is the size of the pool file in bytes. If you are using the `Docker image with Apache Cassandra`_ you can pass this value as an environment variable to the container runtime in Gb and the calculation is done automatically.
|
||||
|
||||
Is important to note that when creating the filesystem in the pmem device certain amount of space of the device is used by the filesystem metadata so the pool_size should be smaller than the total pmem namespace size.
|
||||
|
||||
When using the `Docker image with Apache Cassandra`_, the file `jvm.options` is automatically populated with the environment variables `CASSANDRA_PMEM_POOL_NAME` and `CASSANDRA_FSDAX_POOL_SIZE_GB`.
|
||||
|
||||
devdax
|
||||
------
|
||||
We need to verify the device we want to use is in `devdax` mode
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ndctl create-namespace -fe namespace0.0 --mode=devdax
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
{
|
||||
"dev":"namespace0.0",
|
||||
"mode":"devdax",
|
||||
"map":"dev",
|
||||
"size":"3.94 GiB (4.23 GB)",
|
||||
"uuid":"cb738cc7-711d-4578-bebf-1f7ba02ca169",
|
||||
"daxregion":{
|
||||
"id":0,
|
||||
"size":"3.94 GiB (4.23 GB)",
|
||||
"align":2097152,
|
||||
"devices":[
|
||||
{
|
||||
"chardev":"dax0.0",
|
||||
"size":"3.94 GiB (4.23 GB)"
|
||||
}
|
||||
]
|
||||
},
|
||||
"align":2097152
|
||||
}
|
||||
|
||||
|
||||
If needed, we can reconfigure it using :command:`ndctl create-namespace -fe <namespace-name> --mode=devdax`.
|
||||
|
||||
Before using a `devdax` device we need to clear the device:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo pmempool rm -vaf /dev/dax0.0
|
||||
|
||||
|
||||
The `jvm.options` configuration for Apache Cassandra should look like the following:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
-Dpmem_path=/dev/dax0.0
|
||||
-Dpool_size=0
|
||||
|
||||
Where
|
||||
* pmem_path is the `devdax` device.
|
||||
* pool_size=0 indicates to use the entire `devdax` device.
|
||||
|
||||
When using the `Docker image with Apache Cassandra`_, the file `jvm.options` is automatically populated.
|
||||
|
||||
|
||||
Run the DBRS Container
|
||||
======================
|
||||
|
||||
Replace `<image-id>` in the following commands with the name of the image you are using.
|
||||
|
||||
In `devdax` mode:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --device=/<devdax-device>:/dev/dax0.0 --ulimit nofile=262144:262144 -p 9042:9042 -p 7000:7000 -it --name cassandra-test <image-id>
|
||||
|
||||
|
||||
In `fsdax` mode:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --mount type=bind,source=/<fsdax-mountpoint>,target=/mnt/pmem --ulimit nofile=262144:262144 -p 9042:9042 -p 7000:7000 -it -e 'CASSANDRA_FSDAX_POOL_SIZE_GB=<fsdax-pool-size-in-gb>' --name cassandra-test <image-id>
|
||||
|
||||
|
||||
Container Configuration
|
||||
=======================
|
||||
|
||||
Using environment variables
|
||||
---------------------------
|
||||
|
||||
The container listens on the primary container IP address, but if required, some parameters can be provided as environment variables using `--env`.
|
||||
|
||||
* `CASSANDRA_CLUSTER_NAME` Cassandra cluster name, by default `Cassandra Cluster`
|
||||
* `CASSANDRA_LISTEN_ADDRESS` Cassandra listen address
|
||||
* `CASSANDRA_RPC_ADDRESS` Cassandra RPC address
|
||||
* `CASSANDRA_SEED_ADDRESSES` A comma separated list of hosts in the cluster, if not provided, cassandra is going to run as a single node.
|
||||
* `CASSANDRA_SNITCH` The snitch type for the cluster, by default it is `SimpleSnitch`, for more complex snitches you can mount your own `cassandra-rackdc.properties` file.
|
||||
* `LOCAL_JMX` If set to `no` the JMX service will listen on all IP addresses, the default is `yes` and listens just on localhost 127.0.0.1
|
||||
* `JVM_OPTS` When set you can pass additional arguments to the JVM for cassandra execution, for example for specifying memory heap sizes `JVM_OPTS=-Xms16G -Xmx16G -Xmn12G`
|
||||
|
||||
When using PMEM in `fsdax` mode, there are some parameters to control the allocation of memory:
|
||||
|
||||
|
||||
* `CASSANDRA_FSDAX_POOL_SIZE_GB` The size of the fsdax pool in GB, if it is not specified the pool size is `1`
|
||||
* `CASSANDRA_PMEM_POOL_NAME` The filename of the pool created in PMEM, by default `cassandra_pool`
|
||||
|
||||
Using custom files
|
||||
------------------
|
||||
|
||||
For more complex deployments it is also possible to provide custom `cassandra.yaml` and `jvm.options` files as shown below:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --mount type=bind,source=/<fsdax-mountpoint>,target=/mnt/pmem -it --ulimit nofile=262144:262144 --mount type=bind,source=/<path-to-file>/cassandra.yaml,target=/workspace/cassandra/conf/cassandra.yaml --mount type=bind,source=/path-to-file>/jvm.options,target=/workspace/cassandra/conf/jvm.options --name cassandra-custom-files
|
||||
|
||||
|
||||
Clustering
|
||||
==========
|
||||
|
||||
For a simple two node cluster using PMEM in `fsdax` mode on both containers:
|
||||
|
||||
Node 1
|
||||
------
|
||||
|
||||
* IP: 172.17.0.2
|
||||
* PMEM mountpoint: /mnt/pmem1
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --mount type=bind,source=/mnt/pmem1,target=/mnt/pmem --ulimit nofile=262144:262144 -it -e 'CASSANDRA_FSDAX_POOL_SIZE_GB=2' -e 'CASSANDRA_SEED_ADDRESSES=172.17.0.2:7000,172.17.0.3:7000' --name cassandra-node1 <image-id>
|
||||
|
||||
|
||||
Node 2
|
||||
------
|
||||
|
||||
* IP: 172.17.0.3
|
||||
* PMEM mountpoint: /mnt/pmem2
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --mount type=bind,source=/mnt/pmem2,target=/mnt/pmem --ulimit nofile=262144:262144 -it -e 'CASSANDRA_FSDAX_POOL_SIZE_GB=2' -e 'CASSANDRA_SEED_ADDRESSES=172.17.0.2:7000,172.17.0.3:7000' --name cassandra-node2 <image-id>
|
||||
|
||||
|
||||
Once both nodes are running, eventually the gossip is settled and we can use `nodetool` on either container to check cluster status.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker exec -it <container-id> bash /workspace/cassandra/bin/nodetool status
|
||||
|
||||
|
||||
The output should look similar to this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
||||
Datacenter: datacenter1
|
||||
=======================
|
||||
Status=Up/Down
|
||||
|/ State=Normal/Leaving/Joining/Moving
|
||||
-- Address Load Tokens Owns (effective) Host ID Rack
|
||||
UN 172.17.0.3 0 bytes 256 100.0% 22387159-8192-41cf-8b6c-8bf0e1049eb7 rack1
|
||||
UN 172.17.0.2 0 bytes 256 100.0% 219b56ba-c07c-400b-a018-a5dc20edeb09 rack1
|
||||
|
||||
|
||||
|
||||
Persistence
|
||||
===========
|
||||
|
||||
By default you can access the data written to Apache Cassandra as long as the container exists. In order to persist the data past that, you can mount volumes or bind mounts on :file:`/workspace/cassandra/data` and :file:`/workspace/cassandra/logs` and in this way the data can still be accessed once the container is deleted.
|
||||
|
||||
Deploy An Apache Cassandra-PMEM cluster on Kubernetes*
|
||||
******************************************************
|
||||
|
||||
Many containerized workloads are deployed in clusters and orchestration software like Kubernetes can be useful. We will use the `cassandra-pmem-helm`_ Helm* chart in this example.
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
* Kubectl* must be configured to access the Kubernetes Cluster
|
||||
|
||||
* A Kubernetes cluster with `pmem-csi`_ enabled
|
||||
|
||||
* The Kubernetes cluster must have `helm`_ and tiller installed
|
||||
|
||||
* PMEM hardware
|
||||
|
||||
.. important::
|
||||
|
||||
When selecting the `fsdax` pool file size, it is important to consider that when requesting a volume, certain amount of space is used by the filesystem metadata on that volume and the available space turns out to be less than total amount specified. Taking this into consideration the size of the fsdax pool file should be ~2G less than the total volume size requested.
|
||||
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
In order to configure the Apache Cassandra PMEM cluster some variables and values are provided. These values are set in :file:`test/cassandra-pmem-helm/values.yaml`, and can be modified according to your specific needs. A summary of those parameters is shown below:
|
||||
|
||||
|
||||
* clusterName: The cluster Name set across all deployed nodes
|
||||
* replicaCount: The number of nodes in the cluster to be deployed
|
||||
* image.repository: The address of the container registry where the cassandra-pmem image should be pulled
|
||||
* image.tag: The tag of the image to be pulled during deployment
|
||||
* image.name: The name of the image to be pulled during deployment
|
||||
* pmem.containerPmemAllocation: The size of the persistent volume claim to be used as heap, it uses the storage class `pmem-csi-sc-ext4` from pmem-csi The size of the fsdax pool to be created inside the persistent volume claim, in practice it shuld be `1G` less than pmem.containerPmemAllocation
|
||||
* pmem.fsdaxPoolSizeInGB: The size of the fsdax pool to be created inside the persistent volume claim, in practice it should be 1G less than pmem.containerPmemAllocation
|
||||
* enablePersistence: If set to `true`, K8s persistent volumes are deployed to store data and logs
|
||||
* persistentVolumes.logsVolumeSize: The size of the persistent volume used for storing logs on each node, the default is `4G`
|
||||
* persistentVolumes.dataVolumeSize: The size of the persistent volume used for storing data on each node, the default is `4G`
|
||||
* persistentVolumes.logsStorageClass: Storage class used by the logs pvc, by default it uses `pmem-csi-sc-ext4`
|
||||
* persistentVolumes.dataStorageClass: Storage class used by the data pvc, by default it uses `pmem-csi-sc-ext4`
|
||||
* provideCustomConfig: If set to `true`, it mounts all the files located on `<helm-chart-dir>/files/conf` on `/workspace/cassandra/conf` inside each container in order to provide a way to customize the deployment beyond the options provided here
|
||||
* exposeJmxPort: When set to `true` it exposes the JMX port as part of the Kubernetes headless service. It should be used together with `enableAdditionalFilesConfigMap` in order to provide authentication files needed for JMX when the remote connections are allowed. When set to `false` only local access through 127.0.0.1 is granted and no additional authentication is needed.
|
||||
* enableClientToolsPod: If set to `true`, an additional pod independent from the cluster is deployed, this pod contains various Cassandra client tools and mounts test profiles located under `<helm-chart-dir>/files/testProfiles` to `/testProfiles` inside the pod. This pod is useful to test and launch benchmarks
|
||||
* enableAdditionalFilesConfigMap: When set to true, it takes the files located in `<helm-chart-dir>/files/additionalFiles` and mount them in `/etc/cassandra` inside the pods, some additional files for cassandra can be stored here, such as JMX auth files
|
||||
* jvmOpts.enabled: If set to `true` the environment variable `JVM_OPTS` is overriden with the value provided on jvmOpts.value
|
||||
* jvmOpts.value: Sets the value of the environment variable `JVM_OPTS`, in this way some java runtime configurations can be provided such as RAM heap usage
|
||||
* resources.enabled: if set to `true`, the resource constraints are set on each pod using the values under resources.requests and resources.limits
|
||||
* resources.requests.memory: Initial resource allocation for each pod in the cluster
|
||||
* resources.request.cpu: Initial resource allocation for each pod in the cluster
|
||||
* resources.limits.memory: Limits for memory allocation for each pod in the cluster
|
||||
* resources.limits.cpu: Limits for cpu allocation for each pod in the cluster
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Once all the configurations are set, to install the chart inside a given Kubernetes cluster you must run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
helm install ./cassandra-pmem-helm
|
||||
|
||||
|
||||
Eventually all the given nodes will be shown as running using :command:`kubectl get pods`.
|
||||
|
||||
|
||||
Running DBRS with Redis
|
||||
***********************
|
||||
|
||||
The Redis stack application is enabled for a multinode Kubernetes environment using Intel Optane DCPMM persistent memory DIMMs in fsdax mode for storage.
|
||||
|
||||
The source code used for this application can be found in the `Github repository`_
|
||||
|
||||
The following examples will use the `Docker image with Redis`_. You can also build your own image with Docker by using the :file:`Dockerfile` and running with this command
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build --force-rm --no-cache -f Dockerfile -t ${DOCKER_IMAGE} .
|
||||
|
||||
|
||||
|
||||
Single node
|
||||
===========
|
||||
|
||||
Prior to starting the container, you will need to have the Intel Optane DCPMM module in fsdax with a file system and mounted in `/mnt/dax0` as shown above.
|
||||
|
||||
Use the following to start the container, replacing ${DOCKER_IMAGE} with the name of the image you are using.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --mount type=bind,source=/mnt/dax0,target=/mnt/pmem0 -i -d --name pmem-redis ${DOCKER_IMAGE} --nvm-maxcapacity 200 --nvm-dir /mnt/pmem0 --nvm-threshold 64 --protected-mode no
|
||||
|
||||
|
||||
|
||||
|
||||
Redis Operator in a Kubernetes cluster
|
||||
======================================
|
||||
|
||||
After setting up :ref:`kubernetes` in |CL|, you will need to enable it to support DCPMM using the pmem-cls driver. To install the driver follow the instructions in the `pmem-csi`_ repository.
|
||||
|
||||
We are using source code from the `Redis operator`_ .
|
||||
|
||||
.. note::
|
||||
|
||||
If you already have a redis-operator, you will need to delete it before installing a new one.
|
||||
|
||||
|
||||
|
||||
|
||||
After installing the operator you are ready to deploy redisfailover instances using a yaml file, like this `example for persistent memory`_. You can download it and change the source of the image to reflect your environment. We have named our yaml `redis-failover.yml`
|
||||
|
||||
To start a redisfailover instance in Kubernetes run the following
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kubectl create -f redis-failover.yml
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
There is a `known issue`_ in which the sentinels do not have enough memory to create the InitContainer. The current workaround is to build the image increasing the limits for the InitContainer memory to 32Mb
|
||||
|
||||
|
||||
|
||||
|
||||
.. _Intel Download Center: https://downloadcenter.intel.com/download/28695/Intel-Server-Board-S2600WF-Family-BIOS-and-Firmware-Update-Package-for-UEFI
|
||||
|
||||
.. _Quick Start Guide: https://software.intel.com/en-us/articles/quick-start-guide-configure-intel-optane-dc-persistent-memory-on-linux
|
||||
|
||||
.. _Managing NVDIMMs: https://docs.pmem.io/ndctl-users-guide/managing-nvdimms
|
||||
|
||||
.. _Configure, Manage, and Profile: https://software.intel.com/en-us/articles/configure-manage-and-profile-intel-optane-dc-persistent-memory-modules
|
||||
|
||||
.. _DBRS github repository: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dbrs
|
||||
|
||||
.. _build-cassandra-pmem.sh: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dbrs/cassandra/scripts/
|
||||
|
||||
.. _cassandra-pmem-helm: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dbrs/cassandra/cassandra-pmem-helm
|
||||
|
||||
.. _helm: https://helm.sh/
|
||||
|
||||
.. _Github repository: https://github.com/pmem/pmem-redis
|
||||
|
||||
.. _Redis operator: https://github.com/spotahome/redis-operator
|
||||
|
||||
.. _example for persistent memory: https://github.com/spotahome/redis-operator/blob/master/example/redisfailover/pmem.yaml
|
||||
|
||||
.. _known issue: https://github.com/spotahome/redis-operator/issues/176
|
||||
|
||||
.. _Docker image with Apache Cassandra: https://hub.docker.com/r/clearlinux/stacks-dbrs-cassandra
|
||||
|
||||
.. _Docker image with Redis: https://hub.docker.com/r/clearlinux/stacks-dbrs-redis
|
||||
|
||||
.. _Intel Optane DC PMM: https://www.intel.com/content/www/us/en/architecture-and-technology/optane-technology/optane-for-data-centers.html
|
||||
|
||||
.. _pmem-csi: https://github.com/intel/pmem-csi/blob/release-0.5/README.md
|
||||
|
||||
.. _DBRS Terms of Use: https://clearlinux.org/stacks/database/terms-of-use
|
||||
|
||||
.. _release announcement: https://clearlinux.org/news-blogs/database-reference-stack-dbrs-v10-now-available
|
||||
+67
-210
@@ -59,12 +59,27 @@ Stack features
|
||||
software within the work has its own license. Please see the `DLRS Terms of Use`_
|
||||
for more details about licensing and usage of the Deep Learning Reference Stack.
|
||||
|
||||
Version compatibility
|
||||
=====================
|
||||
|
||||
We validated the steps in this guide against the following software package versions:
|
||||
|
||||
* |CL| 26240 (Minimum supported version)
|
||||
* Docker 18.06.1
|
||||
* Kubernetes 1.11.3
|
||||
* Go 1.11.12
|
||||
|
||||
.. note::
|
||||
|
||||
The Deep Learning Reference Stack was developed to provide the best user experience when executed on a |CL| host. However, as the stack runs in a container environment, you should be able to complete the following sections of this guide on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services.
|
||||
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
* :ref:`Install <bare-metal-install-desktop>` |CL| on your host system
|
||||
* :command:`containers-basic` bundle
|
||||
* :command:`cloud-native-basic` bundle
|
||||
* Add the :command:`containers-basic` bundle
|
||||
* Add the :command:`cloud-native-basic` bundle
|
||||
|
||||
In |CL|, :command:`containers-basic` includes Docker\*, which is required for
|
||||
TensorFlow and PyTorch benchmarking. Use the :command:`swupd` utility to
|
||||
@@ -92,21 +107,42 @@ bundle. To start Docker, enter:
|
||||
To ensure that Kubernetes is correctly installed and configured, follow the
|
||||
instructions in :ref:`kubernetes`.
|
||||
|
||||
Version compatibility
|
||||
=====================
|
||||
|
||||
We validated these steps against the following software package versions:
|
||||
|
||||
* |CL| 26240 (Minimum supported version)
|
||||
* Docker 18.06.1
|
||||
* Kubernetes 1.11.3
|
||||
* Go 1.11.12
|
||||
Kubectl
|
||||
=======
|
||||
|
||||
.. note::
|
||||
You can use kubectl to run commands against your Kubernetes cluster. Refer to
|
||||
the `kubectl overview`_ for details on syntax and operations. Once you have a
|
||||
working cluster on Kubernetes, use the following YAML script to start a pod with
|
||||
a simple shell script, and keep the pod open.
|
||||
|
||||
#. Copy this example.yaml script to your system:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: example-pod
|
||||
labels:
|
||||
app: ex-pod
|
||||
spec:
|
||||
containers:
|
||||
- name: ex-pod-container
|
||||
image: clearlinux/stacks-dlrs-mkl:latest
|
||||
command: ['/bin/bash', '-c', '--']
|
||||
args: [ "while true; do sleep 30; done" ]
|
||||
|
||||
#. Execute the script with kubectl:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kubectl apply –f <path-to-yaml-file>/example.yaml
|
||||
|
||||
|
||||
This script opens a single pod and is helpful to verify your setup is complete and correct. More robust solutions would create a deployment or inject a python script or larger shell script into the container.
|
||||
|
||||
The Deep Learning Reference Stack was developed to provide the best user
|
||||
experience when executed on a |CL| host. However, as the stack runs in a
|
||||
container environment, you should be able to complete the following sections of this guide on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services.
|
||||
|
||||
TensorFlow single and multi-node benchmarks
|
||||
*******************************************
|
||||
@@ -128,8 +164,7 @@ TensorFlow.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --name <image name> --rm -i -t <clearlinux/
|
||||
stacks-dlrs-TYPE> bash
|
||||
docker run --name <image name> --rm -ti <clearlinux/stacks-dlrs-TYPE> bash
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -141,7 +176,7 @@ TensorFlow.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone http://github.com/tensorflow/benchmarks -b cnn_tf_v1.12_compatible
|
||||
git clone http://github.com/tensorflow/benchmarks -b cnn_tf_v1.13_compatible
|
||||
|
||||
#. Execute the benchmark script:
|
||||
|
||||
@@ -193,11 +228,8 @@ single node.
|
||||
--cpu \
|
||||
--model AlexNet
|
||||
|
||||
Kubeflow multi-node benchmarks
|
||||
******************************
|
||||
|
||||
The benchmark workload runs in a Kubernetes cluster. The guide uses
|
||||
`Kubeflow`_ for the Machine Learning workload deployment on three nodes.
|
||||
TensorFlow Training (TFJob) with Kubeflow and DLRS
|
||||
**************************************************
|
||||
|
||||
.. warning::
|
||||
|
||||
@@ -205,180 +237,6 @@ The benchmark workload runs in a Kubernetes cluster. The guide uses
|
||||
must support the Intel® AVX-512 instruction set. Otherwise, an
|
||||
*illegal instruction* error may appear, and you won’t be able to complete this guide.
|
||||
|
||||
|
||||
Kubernetes setup
|
||||
================
|
||||
|
||||
Follow the instructions in the :ref:`kubernetes` tutorial to get set up on
|
||||
|CL|. The Kubernetes community also has instructions for creating a cluster,
|
||||
described in `Creating a single control-plane cluster with kubeadm`_.
|
||||
|
||||
Kubernetes networking
|
||||
=====================
|
||||
|
||||
We used `flannel`_ as the network provider for these tests. If you
|
||||
prefer a different network layer, refer to the Kubernetes network documentation
|
||||
described in `Creating a single control-plane cluster with kubeadm`_ for setup.
|
||||
|
||||
Kubectl
|
||||
=======
|
||||
|
||||
You can use kubectl to run commands against your Kubernetes cluster. Refer to
|
||||
the `Overview of kubectl`_ for details on syntax and operations. Once you have a
|
||||
working cluster on Kubernetes, use the following YAML script to start a pod with
|
||||
a simple shell script, and keep the pod open.
|
||||
|
||||
#. Copy this example.yaml script to your system:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: example-pod
|
||||
labels:
|
||||
app: ex-pod
|
||||
spec:
|
||||
containers:
|
||||
- name: ex-pod-container
|
||||
image: clearlinux/stacks-dlrs-mkl:latest
|
||||
command: ['/bin/bash', '-c', '--']
|
||||
args: [ "while true; do sleep 30; done" ]
|
||||
|
||||
#. Execute the script with kubectl:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kubectl apply –f <path-to-yaml-file>/example.yaml
|
||||
|
||||
This script opens a single pod. More robust solutions would create a deployment
|
||||
or inject a python script or larger shell script into the container.
|
||||
|
||||
Images
|
||||
======
|
||||
|
||||
You must add `launcher.py`_ to the Docker image to include the Deep
|
||||
Learning Reference Stack and put the benchmarks repo in the correct
|
||||
location. Note that this guide uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version.
|
||||
|
||||
From the Docker image, run the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir -p /opt
|
||||
git clone https://github.com/tensorflow/benchmarks.git /opt/tf-benchmarks
|
||||
cp launcher.py /opt
|
||||
chmod u+x /opt/*
|
||||
|
||||
Your entry point becomes: :file:`/opt/launcher.py`.
|
||||
|
||||
This builds an image that can be consumed directly by TFJob from Kubeflow.
|
||||
|
||||
ksonnet\*
|
||||
=========
|
||||
|
||||
Kubeflow uses ksonnet\* to manage deployments, so you must install it
|
||||
before setting up Kubeflow.
|
||||
|
||||
ksonnet was added to the :command:`cloud-native-basic` bundle in |CL| version
|
||||
27550. If you are using an older |CL| version (not recommended), you must
|
||||
manually install ksonnet as described below.
|
||||
|
||||
On |CL|, follow these steps:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
swupd bundle-add go-basic-dev
|
||||
export GOPATH=$HOME/go
|
||||
export PATH=$PATH:$GOPATH/bin
|
||||
go get github.com/ksonnet/ksonnet
|
||||
cd $GOPATH/src/github.com/ksonnet/ksonnet
|
||||
make install
|
||||
|
||||
After the ksonnet installation is complete, ensure that binary `ks` is
|
||||
accessible across the environment.
|
||||
|
||||
Kubeflow
|
||||
========
|
||||
|
||||
Once you have Kubernetes running on your nodes, set up `Kubeflow`_ by
|
||||
following these instructions from the `Getting Started with Kubeflow`_ guide.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export KUBEFLOW_SRC=$HOME/kflow
|
||||
export KUBEFLOW_TAG="v0.4.1"
|
||||
export KFAPP="kflow_app"
|
||||
export K8S_NAMESPACE="kubeflow"
|
||||
|
||||
mkdir ${KUBEFLOW_SRC}
|
||||
cd ${KUBEFLOW_SRC}
|
||||
ks init ${KFAPP}
|
||||
cd ${KFAPP}
|
||||
ks registry add kubeflow github.com/kubeflow/kubeflow/tree/${KUBEFLOW_TAG}/kubeflow
|
||||
ks pkg install kubeflow/common
|
||||
ks pkg install kubeflow/tf-training
|
||||
|
||||
Next, deploy the primary package for our purposes: tf-job-operator.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ks env rm default
|
||||
kubectl create namespace ${K8S_NAMESPACE}
|
||||
ks env add default --namespace "${K8S_NAMESPACE}"
|
||||
ks generate tf-job-operator tf-job-operator
|
||||
ks apply default -c tf-job-operator
|
||||
|
||||
This creates the CustomResourceDefinition (CRD) endpoint to launch a TFJob.
|
||||
|
||||
Run a TFJob
|
||||
===========
|
||||
|
||||
#. Get the ksonnet registries for deploying TFJobs from `dlrs-tfjob`_.
|
||||
|
||||
#. Install the TFJob components as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ks registry add dlrs-tfjob github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-tfjob
|
||||
|
||||
ks pkg install dlrs-tfjob/dlrs-bench
|
||||
|
||||
#. Export the image name to use for the deployment:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export DLRS_IMAGE=<docker_name>
|
||||
|
||||
.. note::
|
||||
|
||||
Replace <docker_name> with the image name you specified in previous steps.
|
||||
|
||||
#. Generate Kubernetes manifests for the workloads and apply them using these
|
||||
commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ks generate dlrs-resnet50 dlrsresnet50 --name=dlrsresnet50 --image=${DLRS_IMAGE}
|
||||
ks generate dlrs-alexnet dlrsalexnet --name=dlrsalexnet --image=${DLRS_IMAGE}
|
||||
ks apply default -c dlrsresnet50
|
||||
ks apply default -c dlrsalexnet
|
||||
|
||||
This replicates and deploys three test setups in your Kubernetes cluster.
|
||||
|
||||
Results of running this section
|
||||
===============================
|
||||
|
||||
You must parse the logs of the Kubernetes pod to retrieve performance
|
||||
data. The pods will still exist post-completion and will be in
|
||||
‘Completed’ state. You can get the logs from any of the pods to inspect the
|
||||
benchmark results. More information about Kubernetes logging is available
|
||||
in the Kubernetes `Logging Architecture`_ documentation.
|
||||
|
||||
|
||||
TensorFlow Training (TFJob) with Kubeflow and DLRS
|
||||
**************************************************
|
||||
|
||||
A `TFJob`_ is Kubeflow's custom resource used to run TensorFlow training jobs on Kubernetes. This example shows how to use a TFJob within the DLRS container.
|
||||
|
||||
Pre-requisites:
|
||||
@@ -389,7 +247,7 @@ Pre-requisites:
|
||||
|
||||
.. note::
|
||||
|
||||
This example proposes a Kubeflow installation with the binary kfctl maintained by `Arrikto`_. Please download the `kfctl tarball`_ to complete the following steps
|
||||
This example proposes a Kubeflow installation using kfctl. Please download the `kfctl tarball`_ to complete the following steps
|
||||
|
||||
#. Download, untar and add to your PATH if necessary
|
||||
|
||||
@@ -400,19 +258,13 @@ Pre-requisites:
|
||||
tar -C ${KFCTL_PATH} -xvf ${KFCTL_PATH}/kfctl_v${kfctl_ver}_linux.tar.gz
|
||||
export PATH=$PATH:${KFCTL_PATH}
|
||||
|
||||
#. Install `MetalLB`_
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kubectl apply -f https://raw.githubusercontent.com/google/metallb/v0.8.1/manifests/metallb.yaml
|
||||
|
||||
#. Install Kubeflow resource and TFJob operators
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Env variables needed for your deployment
|
||||
export KFAPP="<your choice of application directory name>"
|
||||
export CONFIG="https://raw.githubusercontent.com/kubeflow/kubeflow/master/bootstrap/config/kfctl_existing_arrikto.yaml"
|
||||
export CONFIG="https://raw.githubusercontent.com/kubeflow/kubeflow/v0.6.1/bootstrap/config/kfctl_k8s_istio.yaml"
|
||||
|
||||
kfctl init ${KFAPP} --config=${CONFIG} -V
|
||||
cd ${KFAPP}
|
||||
@@ -432,8 +284,7 @@ Pre-requisites:
|
||||
Submitting TFJobs
|
||||
=================
|
||||
|
||||
We provide several `DLRS TFJob`_ examples that use the Deep Learning Reference Stack as the base image for creating the containers to run training workloads in your Kubernetes cluster.
|
||||
|
||||
We provide `DLRS TFJob`_ examples that use the Deep Learning Reference Stack as the base image for creating the containers to run training workloads in your Kubernetes cluster.
|
||||
|
||||
|
||||
Customizing a TFJob
|
||||
@@ -495,6 +346,15 @@ If you'd like to modify the number and type of replicas, resources, persistent v
|
||||
- --batch_size=32
|
||||
- --training_steps=1000
|
||||
|
||||
Results of running this section
|
||||
===============================
|
||||
|
||||
You must parse the logs of the Kubernetes pod to retrieve performance
|
||||
data. The pods will still exist post-completion and will be in
|
||||
‘Completed’ state. You can get the logs from any of the pods to inspect the
|
||||
benchmark results. More information about Kubernetes logging is available
|
||||
in the Kubernetes `Logging Architecture`_ documentation.
|
||||
|
||||
For more information, please refer to:
|
||||
* `Distributed TensorFlow`_
|
||||
* `TFJobs`_
|
||||
@@ -514,13 +374,10 @@ Pre-requisites:
|
||||
Submitting PyTorch Jobs
|
||||
=======================
|
||||
|
||||
We provide several `DLRS PytorchJob`_ examples that use the Deep Learning Reference Stack as the base image for creating the container(s) that will run training workloads in your Kubernetes cluster.
|
||||
We provide `DLRS PytorchJob`_ examples that use the Deep Learning Reference Stack as the base image for creating the container(s) that will run training workloads in your Kubernetes cluster.
|
||||
Select one form the list below:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Using Kubeflow Seldon and OpenVINO* with the Deep Learning Reference Stack
|
||||
**************************************************************************
|
||||
|
||||
@@ -1000,7 +857,7 @@ Related topics
|
||||
|
||||
.. _Jupyter Notebook: https://jupyter.org/
|
||||
|
||||
.. _Overview of kubectl: https://kubernetes.io/docs/reference/kubectl/overview/
|
||||
.. _kubectl overview: https://kubernetes.io/docs/reference/kubectl/overview/
|
||||
|
||||
.. _launcher.py: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow
|
||||
|
||||
|
||||
@@ -113,6 +113,8 @@ for the OpenVINO software stack:
|
||||
The :command:`computer-vision-basic` bundle installs the OpenVINO™ toolkit,
|
||||
and the sample models optimized for Intel® edge platforms.
|
||||
|
||||
.. _convert-dl-models:
|
||||
|
||||
Convert deep learning models
|
||||
============================
|
||||
|
||||
|
||||
+70
-49
@@ -1,58 +1,79 @@
|
||||
.. _clear-linux:
|
||||
|
||||
|CL-PRJ|
|
||||
|CL-PRJ| Documentation
|
||||
#############################################
|
||||
|
||||
Welcome to the |CL-ATTR| documentation pages, the source for |CL| documentation.
|
||||
.. container:: multicolumns
|
||||
|
||||
Our documentation is divided into the following sections:
|
||||
.. container:: column verticalcard
|
||||
|
||||
.. rst-class:: colh2
|
||||
|
||||
Highlights
|
||||
|
||||
:ref:`autospec`
|
||||
**autospec** is a tool to assist in the automated creation and
|
||||
maintenance of RPM packaging in Clear Linux OS.
|
||||
|
||||
:ref:`dlrs`
|
||||
This tutorial shows you how to run benchmarking workloads in Clear
|
||||
Linux OS using TensorFlow\* or PyTorch\* with the Deep Learning
|
||||
Reference Stack.
|
||||
|
||||
:ref:`docker`
|
||||
Clear Linux OS supports multiple containerization platforms,
|
||||
including a Docker solution.
|
||||
|
||||
:ref:`developer-workstation`
|
||||
Developer Workstation helps you find the Bundles you need to start
|
||||
your Clear Linux OS development project.
|
||||
|
||||
.. container:: column verticalcard
|
||||
|
||||
.. rst-class:: colh2
|
||||
|
||||
Quicklinks
|
||||
|
||||
:ref:`get-started`
|
||||
Get up and running fast with Clear Linux\* OS. Use these step-by-step
|
||||
instructions to guide you through the installation of Clear Linux OS
|
||||
from bare metal to live image.
|
||||
|
||||
:ref:`bare-metal-install-desktop`
|
||||
These instructions guide you through the installation of Clear Linux
|
||||
OS on bare metal using a bootable USB drive.
|
||||
|
||||
:ref:`architect-lifecycle`
|
||||
This guide provides DevOps with a model to architect the life-cycle
|
||||
of a Clear Linux OS derivative that integrates custom software and
|
||||
content using distinct workflows.
|
||||
|
||||
:ref:`bundles`
|
||||
Useful bundle commands for working with bundles on the Clear Linux OS.
|
||||
|
||||
.. container:: column featurecard
|
||||
|
||||
.. toctree::
|
||||
:caption: Documentation Contents
|
||||
:maxdepth: 1
|
||||
|
||||
get-started/index
|
||||
about
|
||||
guides/index
|
||||
tutorials/index
|
||||
reference/index
|
||||
FAQ/index
|
||||
collaboration/collaboration
|
||||
|
||||
**Need some help?**
|
||||
|
||||
| `Ask the Clear Linux experts <https://clearlinux.org/community/mailing-list>`_
|
||||
| `Clear Linux Forum <https://community.clearlinux.org/>`_
|
||||
| `IRC-based support <https://webchat.freenode.net/>`_
|
||||
|
||||
|
||||
:ref:`get-started`
|
||||
.. container:: video
|
||||
|
||||
If you are new to |CL|, get started quickly with step-by-step instructions
|
||||
for installing |CL| on bare metal, in a virtual environment, or as a live
|
||||
image on a USB stick.
|
||||
.. raw:: html
|
||||
|
||||
:ref:`about`
|
||||
|
||||
|CL| is different from other Linux distributions.
|
||||
|
||||
Updates, ease of use, and custom derivatives are a few of the differences
|
||||
this section explains. Orient yourself to these differences and why they
|
||||
matter to you.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/JFg-_5xihkE" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen style="padding:10px; background-color: #fff;"></iframe>
|
||||
|
||||
:ref:`guides`
|
||||
|
||||
Guides cover a range of topics from |CL| features and tooling, to system
|
||||
maintenance, network, and stacks.
|
||||
|
||||
:ref:`Use case tutorials <tutorials>`
|
||||
|
||||
Sample use cases, with step-by-step instructions, show how to set up
|
||||
third-party tools and software with |CL|.
|
||||
|
||||
:ref:`reference`
|
||||
|
||||
This section provides additional reference information on the |CL| project.
|
||||
|
||||
:ref:`faq`
|
||||
|
||||
The FAQ section provides answers to commonly asked questions about |CL|.
|
||||
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:hidden:
|
||||
|
||||
get-started/index
|
||||
about
|
||||
guides/index
|
||||
tutorials/index
|
||||
reference/index
|
||||
FAQ/index
|
||||
<iframe width="100%" height="100%" src="https://www.youtube.com/embed/JFg-_5xihkE" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen style="padding:10px; background-color: #fff;"></iframe>
|
||||
@@ -1,83 +0,0 @@
|
||||
.. _collaboration:
|
||||
|
||||
Documentation guidelines
|
||||
########################
|
||||
|
||||
See a missing topic in the documentation? Find an existing document that could
|
||||
be improved? Help us out by contributing! If you haven't contributed before,
|
||||
take a moment to review our `Contribution guidelines`_.
|
||||
|
||||
Do you have questions about the documentation that were not answered by these
|
||||
guidelines? Send your question to the `mailing list`_.
|
||||
|
||||
Contribution guidelines
|
||||
***********************
|
||||
|
||||
The |CL| documentation is hosted in GitHub and is written using
|
||||
reStructuredText. Use our guidelines and best practices to write consistent,
|
||||
readable documentation.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Writing guide: Describes the style we use to keep our documents clear and concise. <writing-guide>
|
||||
Structure and formatting guide: Explains how we organize and format content, using reStructuredText and Sphinx. <structure-formatting>
|
||||
|
||||
How to contribute
|
||||
*****************
|
||||
|
||||
There are multiple ways to contribute and help improve our documentation:
|
||||
|
||||
* **Make a suggestion**: Have a documentation suggestion but no time to write it
|
||||
yourself? Send your suggestion to the `mailing list`_.
|
||||
* **Log an issue**: If you find a problem in our documentation (such as typos or
|
||||
out-of-date information), log an issue in the `documentation repository`_.
|
||||
* **Contribute directly via GitHub**: Whether you've found a typo, have better
|
||||
instructions or examples, or have a new page to add, submit your improvement
|
||||
or addition as a pull request on the `documentation repository`_.
|
||||
* **Test documentation**: Step through our instructional guides and tutorials to
|
||||
verify the instructions. Log or correct any out-of-date information.
|
||||
|
||||
All contributions must follow our `code of conduct`_.
|
||||
|
||||
Contribute via GitHub
|
||||
*********************
|
||||
|
||||
Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_:
|
||||
|
||||
#. Clone the `documentation repository`_.
|
||||
|
||||
#. Create your own fork of the repository.
|
||||
|
||||
#. Create a branch for your contribution.
|
||||
|
||||
#. Add your commits.
|
||||
|
||||
#. Open a pull request.
|
||||
|
||||
#. Discuss, review, and update your contributions.
|
||||
|
||||
#. Once the maintainer approves, your contribution is merged and published as
|
||||
part of the documentation.
|
||||
|
||||
.. _references:
|
||||
|
||||
References
|
||||
**********
|
||||
|
||||
We use the following references to guide the grammar, style, and formatting of
|
||||
our documentation:
|
||||
|
||||
* `Microsoft Writing Style Guide`_
|
||||
* `Merriam-Webster Dictionary`_
|
||||
* The Chicago Manual of Style (15th edition), The University of Chicago Press
|
||||
* Microsoft Press Computer Dictionary, Microsoft Press
|
||||
* Read Me First!, Oracle Technical Publications
|
||||
|
||||
|
||||
.. _`code of conduct`: https://clearlinux.org/community/code-of-conduct
|
||||
.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
|
||||
.. _GitHub flow: https://guides.github.com/introduction/flow/
|
||||
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
|
||||
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
|
||||
.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/
|
||||
@@ -11,6 +11,5 @@ features.
|
||||
|
||||
compatible-hardware
|
||||
bundles/bundles
|
||||
collaboration/collaboration
|
||||
system-requirements
|
||||
image-types
|
||||
|
||||
@@ -5,7 +5,7 @@ Recommended minimum system requirements
|
||||
|
||||
|CL-ATTR| can run on most modern hardware and is capable of running with
|
||||
modest hardware resources. Out of the box, |CL| can run on a single CPU core, 1
|
||||
GB RAM, and 2 GB of disk space.
|
||||
GB RAM, and 2 GB of disk space.
|
||||
|
||||
For use cases requiring minimal resources, |CL| :ref:`about <about>` can
|
||||
be used to create a highly customized installation that can even run on a
|
||||
@@ -29,7 +29,7 @@ System requirements
|
||||
*******************
|
||||
|
||||
|CL| requires an x86 64-bit processor which supports Intel® Streaming SIMD
|
||||
Extensions 4.1 (Intel® SSE 4.1), and it requires a system that supports UEFI.
|
||||
Extensions 4.2 (Intel® SSE 4.2), and it requires a system that supports UEFI.
|
||||
|
||||
The |CL| installer performs a system compatibility check upon booting. To
|
||||
manually verify system compatibility with |CL|, run the :ref:`compatibility
|
||||
@@ -39,13 +39,12 @@ these features:
|
||||
* Instruction Set:
|
||||
|
||||
- 64-bit
|
||||
|
||||
|
||||
* Instruction Set Extensions:
|
||||
|
||||
- Supplemental Streaming SIMD Extension 3 (Intel® SSSE3)
|
||||
- Intel® Streaming SIMD Extensions 4.1 (Intel® SSE 4.1)
|
||||
- Intel® Streaming SIMD Extensions 4.2 (Intel® SSE 4.2)
|
||||
- Intel® Advanced Encryption Standard New Instructions (Intel® AES-NI)
|
||||
- Carry-less Multiplication (PCLMUL)
|
||||
|
||||
The following processor families have been verified to run |CL|:
|
||||
|
||||
@@ -4,7 +4,16 @@ Apache\* Spark\*
|
||||
################
|
||||
|
||||
This tutorial describes how to install, configure, and run Apache Spark on
|
||||
|CL-ATTR|. Apache Spark is a fast general-purpose cluster computing system with
|
||||
|CL-ATTR| on a single machine running the master daemon and a worker daemon.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
Apache Spark is a fast, general-purpose cluster computing system with
|
||||
the following features:
|
||||
|
||||
* Provides high-level APIs in Java\*, Scala\*, Python\*, and R\*.
|
||||
@@ -12,27 +21,26 @@ the following features:
|
||||
* Supports high-level tools including Spark SQL, MLlib, GraphX, and Spark
|
||||
Streaming.
|
||||
|
||||
In this tutorial, you will install Spark on a single machine running the
|
||||
master daemon and a worker daemon.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
This tutorial assumes you have installed |CL| on your host system.
|
||||
For detailed instructions on installing |CL| on a bare metal system, visit
|
||||
the :ref:`bare metal installation guide <bare-metal-install-desktop>`.
|
||||
* |CL| installed on your host system.
|
||||
|
||||
Before you install any new packages, update |CL| with the following command:
|
||||
For detailed instructions on installing |CL| on a bare metal system, visit
|
||||
the :ref:`bare metal installation guide <bare-metal-install-desktop>`.
|
||||
|
||||
.. code-block:: bash
|
||||
* Before installing any new packages, update |CL| with the following command:
|
||||
|
||||
sudo swupd update
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd update
|
||||
|
||||
Install Apache Spark
|
||||
********************
|
||||
|
||||
Apache Spark is included in the :file:`big-data-basic` bundle. To install the
|
||||
framework, enter:
|
||||
Apache Spark is included in the :command:`big-data-basic` bundle. To install the
|
||||
framework, run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -41,14 +49,14 @@ framework, enter:
|
||||
Configure Apache Spark
|
||||
**********************
|
||||
|
||||
#. Create the configuration directory with the command:
|
||||
#. Create the configuration directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir /etc/spark
|
||||
|
||||
#. Copy the default templates from :file:`/usr/share/defaults/spark` to
|
||||
:file:`/etc/spark` with the command:
|
||||
:file:`/etc/spark`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -58,8 +66,7 @@ Configure Apache Spark
|
||||
files under the :file:`/usr/share/defaults` directory. The software
|
||||
updater overwrites those files.
|
||||
|
||||
|
||||
#. Copy the template files below to create custom configuration files:
|
||||
#. Copy the template files shown below to create custom configuration files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -80,7 +87,8 @@ Configure Apache Spark
|
||||
view information needed later in this tutorial.
|
||||
|
||||
#. Edit the :file:`/etc/spark/spark-defaults.conf` file and update the
|
||||
`spark.master` variable with the `SPARK_MASTER_HOST` address and port `7077`.
|
||||
:envvar:`spark.master` variable with the `SPARK_MASTER_HOST` address and port
|
||||
`7077`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -89,14 +97,14 @@ Configure Apache Spark
|
||||
Start the master server and a worker daemon
|
||||
*******************************************
|
||||
|
||||
#. Start the master server using:
|
||||
#. Start the master server:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo /usr/share/apache-spark/sbin/./start-master.sh
|
||||
|
||||
#. Start one worker daemon and connect it to the master using the
|
||||
`spark.master` variable defined earlier:
|
||||
:envvar:`spark.master` variable defined earlier:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -130,5 +138,5 @@ Run the Spark wordcount example
|
||||
|
||||
**Congratulations!**
|
||||
|
||||
You successfully installed and set up a standalone Apache Spark cluster.
|
||||
Additionally, you ran a simple wordcount example.
|
||||
You have successfully installed and set up a standalone Apache Spark cluster,
|
||||
and ran a simple wordcount example.
|
||||
|
||||
@@ -3,12 +3,22 @@
|
||||
Migrate Clear Containers to Kata Containers\*
|
||||
#############################################
|
||||
|
||||
`Clear Containers`_ and `Kata Containers`_ can co-exist in the same system.
|
||||
Both can be installed through the :file:`containers-virt bundle`. However, we
|
||||
recommend that you migrate to Kata Containers because Clear Containers is no
|
||||
longer maintained_ and will soon be deprecated on |CL-ATTR|.
|
||||
This tutorial explains how to migrate from Clear Containers to Kata Containers.
|
||||
|
||||
This guide describes how to migrate to Kata Containers and assumes that:
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
`Clear Containers`_ and `Kata Containers`_ can co-exist in the same system.
|
||||
Both can be installed through the :command:`containers-virt` bundle. However,
|
||||
we recommend that you migrate to Kata Containers because Clear Containers is no
|
||||
longer `maintained`_ and will soon be deprecated on |CL-ATTR|.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
* Clear Containers is on a Docker\* system.
|
||||
* Kata Containers is installed. See :ref:`kata`.
|
||||
|
||||
@@ -19,7 +19,7 @@ This tutorial covers:
|
||||
If you want to use |CL| as a Docker container image, refer to the
|
||||
official |CL| container image
|
||||
`published on Docker* Hub <https://hub.docker.com/_/clearlinux/>`_
|
||||
and our guide to :ref:`custom-clear-container`.
|
||||
and our guide to :ref:`container-image-new`.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
@@ -10,6 +10,7 @@ Explore our tutorials to discover what you can do with |CL|!
|
||||
:glob:
|
||||
|
||||
*
|
||||
multi-boot/*
|
||||
|
||||
Archive
|
||||
*******
|
||||
|
||||
@@ -3,9 +3,8 @@
|
||||
Kubernetes\*
|
||||
############
|
||||
|
||||
This tutorial describes how to install, configure, and run the
|
||||
`Kubernetes container orchestration system`_ on |CL-ATTR| using CRI+O and
|
||||
kata-runtime.
|
||||
This tutorial describes how to install, configure, and start the
|
||||
`Kubernetes container orchestration system`_ on |CL-ATTR| using CRI+O and kata-runtime.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
@@ -97,7 +96,7 @@ deployment and your security needs.
|
||||
.. note::
|
||||
|
||||
Swap will be enabled at next reboot, causing failures in
|
||||
your cluster.
|
||||
your cluster if you choose this method.
|
||||
|
||||
or:
|
||||
|
||||
@@ -137,8 +136,7 @@ deployment and your security needs.
|
||||
Configure and run Kubernetes
|
||||
****************************
|
||||
|
||||
This section describes how to configure and run Kubernetes with CRI-O and
|
||||
kata-runtime.
|
||||
This section describes how to configure and run Kubernetes with CRI-O and kata-runtime. We will be using the :command:`kubectl` command-line interface to control Kubernetes.
|
||||
|
||||
Configure and run CRI-O + kata-runtime
|
||||
======================================
|
||||
@@ -149,21 +147,22 @@ Configure and run CRI-O + kata-runtime
|
||||
|
||||
sudo systemctl enable crio.service
|
||||
|
||||
#. Enter the commands:
|
||||
#. Enter these commands to restart the system services so that CRI-O will be restarted, and will automatically start with every reboot.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart crio
|
||||
|
||||
#. Initialize the master control plane with the command below and follow the
|
||||
displayed instructions to set up `kubectl`:
|
||||
|
||||
|
||||
#. Initialize the master control plane with the command below and follow the displayed instructions to set up `kubectl`. The :command:`init` command initializes a Kubernetes `control-plane node`_. If you will be adding a pod network add-on, you will need to add configuration to the :command:`init` command line. see the `Install pod network add-on`_ section for details.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo kubeadm init --cri-socket=/run/crio/crio.sock
|
||||
|
||||
#. Register kata-runtime as a RuntimeClass handler:
|
||||
#. Register kata-runtime as a `RuntimeClass handler`_:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -181,26 +180,23 @@ Configure and run CRI-O + kata-runtime
|
||||
handler: kata
|
||||
EOF
|
||||
|
||||
|
||||
Install pod network add-on
|
||||
**************************
|
||||
|
||||
You must choose and install a `pod network add-on`_ to allow your pods to
|
||||
communicate. Check whether or not your add-on requires special flags when you
|
||||
initialize the master control plane.
|
||||
You must choose and install a `pod network add-on`_ to allow your pods to communicate. Check whether or not your add-on requires special flags when you initialize the master control plane.
|
||||
|
||||
**Notes about flannel add-on**
|
||||
|
||||
If you choose the `flannel` add-on, then you must add the following to the
|
||||
`kubeadm init` command:
|
||||
If you choose the `flannel` add-on, then you must add the following to the :command:`kubeadm init` command:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
--pod-network-cidr 10.244.0.0/16
|
||||
|
||||
Furthermore, if you are using CRI-O and `flannel` and you want to use
|
||||
Kata Containers, edit the :file:`/etc/crio/crio.conf` file to add:
|
||||
Furthermore, if you are using CRI-O and `flannel` and you want to use Kata Containers, edit the :file:`/etc/crio/crio.conf` file to add:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
[crio.runtime]
|
||||
manage_network_ns_lifecycle = true
|
||||
@@ -208,22 +204,16 @@ Kata Containers, edit the :file:`/etc/crio/crio.conf` file to add:
|
||||
Use your cluster
|
||||
****************
|
||||
|
||||
Once your master control plane is successfully initialized, instructions on
|
||||
how to use your cluster and its *IP*, *token*, and *hash* values are
|
||||
displayed. It is important that you record the cluster values because they
|
||||
are needed when joining worker nodes to the cluster. Some values have a valid
|
||||
period. The values are presented in a format similar to:
|
||||
Once your master control plane is successfully initialized, instructions on how to use your cluster and its *IP*, *token*, and *hash* values are displayed. It is important that you record the cluster values because you need them to join worker nodes to the cluster. Some values have a valid period. The values are presented in a format similar to:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kubeadm join <master-ip>:<master-port> --token <token> --discovery-token-ca-cert-hash <hash>
|
||||
|
||||
|
||||
**Congratulations!**
|
||||
|
||||
You've successfully installed and set up Kubernetes in |CL| using CRI-O and
|
||||
kata-runtime. You are now ready to follow on-screen instructions to deploy a
|
||||
pod network to the cluster and join worker nodes with the displayed token
|
||||
and IP information.
|
||||
You've successfully installed and set up Kubernetes in |CL| using CRI-O and kata-runtime. You are now ready to follow on-screen instructions to deploy a pod network to the cluster and join worker nodes with the displayed token and IP information.
|
||||
|
||||
Related topics
|
||||
**************
|
||||
@@ -245,25 +235,16 @@ Read the Kubernetes documentation to learn more about:
|
||||
Cloud native setup automation
|
||||
*****************************
|
||||
|
||||
Optional: Clone the `cloud-native-setup`_ repository on your system and
|
||||
follow the instructions. This repository includes helper scripts to automate
|
||||
configuration.
|
||||
Optional: Clone the `cloud-native-setup`_ repository on your system and follow the instructions. This repository includes helper scripts to automate configuration.
|
||||
|
||||
Package configuration customization (optional)
|
||||
**********************************************
|
||||
|
||||
|CL| is a stateless system that looks for user-defined package configuration
|
||||
files in the :file:`/etc/<package-name>` directory to be used as default. If
|
||||
user-defined files are not found, |CL| uses the distribution-provided
|
||||
configuration files for each package.
|
||||
|CL| is a stateless system that looks for user-defined package configuration files in the :file:`/etc/<package-name>` directory to be used as default. If user-defined files are not found, |CL| uses the distribution-provided configuration files for each package.
|
||||
|
||||
If you customize any of the default package configuration files, you **must**
|
||||
store the customized files in the :file:`/etc/` directory. If you edit any of
|
||||
the distribution-provided default files, your changes will be lost in the
|
||||
next system update.
|
||||
If you customize any of the default package configuration files, you **must** store the customized files in the :file:`/etc/` directory. If you edit any of the distribution-provided default files, your changes will be lost in the next system update as the default files will be overwritten with the updated files.
|
||||
|
||||
For example, to customize CRI-O configuration in your system, run the
|
||||
following commands:
|
||||
For example, to customize CRI-O configuration in your system, run the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -276,14 +257,9 @@ Learn more about :ref:`stateless` in |CL|.
|
||||
Proxy configuration (optional)
|
||||
******************************
|
||||
|
||||
If you use a proxy server, you must set your proxy environment variables and
|
||||
create an appropriate proxy configuration file for both CRI-O services. Consult
|
||||
your IT department if you are behind a corporate proxy for the appropriate
|
||||
values. Ensure that your local IP is **explicitly included** in the environment
|
||||
variable *NO_PROXY*. (Setting *localhost* is not enough.)
|
||||
If you use a proxy server, you must set your proxy environment variables and create an appropriate proxy configuration file for both CRI-O services. Consult your IT department if you are behind a corporate proxy for the appropriate values. Ensure that your local IP is **explicitly included** in the environment variable *NO_PROXY*. (Setting *localhost* is not enough.)
|
||||
|
||||
If you have already set your proxy environment variables, run the following
|
||||
commands as a shell script to configure all of these services in one step:
|
||||
If you have already set your proxy environment variables, run the following commands as a shell script to configure all of these services in one step:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -304,44 +280,33 @@ Troubleshooting
|
||||
|
||||
* <HOSTNAME> not found in <IP> message.
|
||||
|
||||
Your DNS server may not be appropriately configured. Try adding an
|
||||
entry to the :file:`/etc/hosts` file with your host's IP and Name.
|
||||
Your DNS server may not be appropriately configured. Try adding an entry to the :file:`/etc/hosts` file with your host's IP and Name.
|
||||
|
||||
For example: 100.200.50.20 myhost
|
||||
|
||||
Use the commands :command:`hostname` and :command:`hostname -I`
|
||||
to retrieve them.
|
||||
Use the commands :command:`hostname` and :command:`hostname -I` to retrieve them.
|
||||
|
||||
* Images cannot be pulled.
|
||||
|
||||
You may be behind a proxy server. Try configuring your proxy settings,
|
||||
using the environment variables *HTTP_PROXY*, *HTTPS_PROXY*, and *NO_PROXY*
|
||||
as required in your environment.
|
||||
You may be behind a proxy server. Try configuring your proxy settings, using the environment variables *HTTP_PROXY*, *HTTPS_PROXY*, and *NO_PROXY* as required in your environment.
|
||||
|
||||
* Connection refused error.
|
||||
|
||||
If you are behind a proxy server, you may need to add the master's IP to
|
||||
the environment variable *NO_PROXY*.
|
||||
If you are behind a proxy server, you may need to add the master's IP to the environment variable *NO_PROXY*.
|
||||
|
||||
* Connection timed-out or Access Refused errors.
|
||||
|
||||
You must ensure that the appropriate proxy settings are available from the
|
||||
same terminal where you will initialize the control plane. To verify the
|
||||
proxy settings that Kubernetes will actually use, run the commands:
|
||||
You must ensure that the appropriate proxy settings are available from the same terminal where you will initialize the control plane. To verify the proxy settings that Kubernetes will actually use, run the commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
echo $HTTP_PROXY
|
||||
echo $HTTPS_PROXY
|
||||
echo $NO_PROXY
|
||||
echo $HTTP_PROXY
|
||||
echo $HTTPS_PROXY
|
||||
echo $NO_PROXY
|
||||
|
||||
If the displayed proxy values are different from your assigned values, the
|
||||
cluster initialization will fail. Contact your IT support team to learn how
|
||||
to set the proxy variables permanently, and how to make them available for
|
||||
all the types of access that you will use, such as remote SSH access.
|
||||
If the displayed proxy values are different from your assigned values, the cluster initialization will fail. Contact your IT support team to learn how to set the proxy variables permanently, and how to make them available for all the types of access that you will use, such as remote SSH access.
|
||||
|
||||
If the result of the above commands is blank, you may need to add a
|
||||
``profile`` to the :file:`/etc` directory. To do so, follow these steps.
|
||||
If the result of the above commands is blank, you may need to add a ``profile`` to the :file:`/etc` directory. To do so, follow these steps.
|
||||
|
||||
#. Create a `profile` in :file:`/etc`
|
||||
|
||||
@@ -349,8 +314,7 @@ Troubleshooting
|
||||
|
||||
sudo touch profile
|
||||
|
||||
#. With your preferred editor, open `profile`, and enter your proxy settings.
|
||||
An example is shown below.
|
||||
#. With your preferred editor, open `profile`, and enter your proxy settings. An example is shown below.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -365,8 +329,7 @@ Troubleshooting
|
||||
|
||||
#. Save and exit the `profile`.
|
||||
|
||||
#. Update your system's environment settings by executing the following
|
||||
command:
|
||||
#. Update your system's environment settings by executing the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -382,8 +345,7 @@ Troubleshooting
|
||||
|
||||
* Missing environment variables.
|
||||
|
||||
If you are behind a proxy server, pass environment variables by adding *-E*
|
||||
to the command that initializes the master control plane.
|
||||
If you are behind a proxy server, pass environment variables by adding *-E* to the command that initializes the master control plane.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -409,3 +371,7 @@ Troubleshooting
|
||||
.. _Joining your nodes: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#join-nodes
|
||||
|
||||
.. _cloud-native-setup: https://github.com/clearlinux/cloud-native-setup/tree/master/clr-k8s-examples
|
||||
|
||||
.. _control-plane node: https://kubernetes.io/docs/concepts/#kubernetes-control-plane
|
||||
|
||||
.. _RuntimeClass handler: https://kubernetes.io/docs/concepts/containers/runtime-class/
|
||||
|
||||
@@ -0,0 +1,246 @@
|
||||
.. _dual-boot-win:
|
||||
|
||||
Dual-boot |CL-ATTR| and Windows\* 10 OS
|
||||
########################################
|
||||
|
||||
This guide shows how to install |CL-ATTR| adjacent to an existing Windows\*
|
||||
10 :abbr:`OS (operating system)`. To add |CL| to an existing Windows installation, follow a method below.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
In this tutorial you'll :ref:`bare-metal-install-desktop` as
|
||||
an additional partition. Alternatively, you may also
|
||||
:ref:`bare-metal-install-server`.
|
||||
|
||||
Method 1: Shrink Windows partition and install |CL|
|
||||
***************************************************
|
||||
For this method, we shrink the Windows 10 OS partition to make space for |CL|.
|
||||
|
||||
#. Boot up the Windows 10 OS.
|
||||
|
||||
#. Launch the :file:`Disk Management` utility found under
|
||||
:guilabel:`Create and format hard disk partitions`.
|
||||
|
||||
#. Right-click the primary Windows partition and select :guilabel:`Shrink Volume...`.
|
||||
|
||||
.. figure:: ../../_figures/multi-boot/dual-boot-win-01.png
|
||||
:scale: 85%
|
||||
:alt: Disk Management > Shrink Volume
|
||||
|
||||
Figure 1: Disk Management > Shrink Volume.
|
||||
|
||||
#. Shrink the size of the partition by at least the following amount:
|
||||
|
||||
* For :ref:`installing the live desktop <bare-metal-install-desktop>`,
|
||||
allow at least 21GB.
|
||||
|
||||
* For :ref:`installing the live server <bare-metal-install-server>`,
|
||||
allow at least 4GB.
|
||||
|
||||
|
||||
#. We shrink C by about 21 GB, as shown in Figure 2.
|
||||
|
||||
.. figure:: ../../_figures/multi-boot/dual-boot-win-02.png
|
||||
:scale: 85%
|
||||
:alt: Shrink C
|
||||
|
||||
Figure 2: Shrink C.
|
||||
|
||||
#. Shutdown the Windows 10 OS.
|
||||
|
||||
#. Follow the instructions to :ref:`bare-metal-install-desktop`.
|
||||
|
||||
#. After booting from the |CL| image, select the icon to
|
||||
launch the installer.
|
||||
|
||||
#. Click :guilabel:`Select Installation Media`.
|
||||
|
||||
#. Select :guilabel:`Safe Installation`.
|
||||
|
||||
#. Go through the remaining steps to install |CL|.
|
||||
|
||||
#. Shut down your system and remove the USB.
|
||||
|
||||
#. Reboot.
|
||||
|
||||
#. During the BIOS POST stage, press :kbd:`F10`, or the proper F-key for your
|
||||
system, to launch the :guilabel:`Boot Menu`.
|
||||
|
||||
.. figure:: ../../_figures/multi-boot/dual-boot-win-03.png
|
||||
:scale: 85%
|
||||
:alt: Boot menu
|
||||
|
||||
Figure 3: Boot menu
|
||||
|
||||
#. In the :guilabel:`Boot Menu`, use the arrow to select the
|
||||
:guilabel:`OS bootloader` as boot device (highlighted).
|
||||
|
||||
Some BIOSes do not support listing multiple partitions. In this case,
|
||||
it will only show one bootable partition.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you don't want to use the BIOS boot menu each time to select an OS,
|
||||
follow :ref:`Advanced: Use systemd-boot to boot Windows 10 OS and |CL| <advanced-systemd-boot>`.
|
||||
|
||||
Method 2: Add another hard disk to your system where you install |CL|
|
||||
*********************************************************************
|
||||
|
||||
#. Shutdown your system.
|
||||
|
||||
#. Open your system and attach another hard drive.
|
||||
|
||||
#. Power up your system.
|
||||
|
||||
#. Follow the instructions in :ref:`bare-metal-install-desktop`, and launch
|
||||
the |CL| installer.
|
||||
|
||||
#. In the :guilabel:`Required options` tab, choose :guilabel:`Select
|
||||
Installation Media`.
|
||||
|
||||
#. Within that menu, select :guilabel:`Destructive Installation`, and
|
||||
select the new hard drive from the device list.
|
||||
|
||||
.. note::
|
||||
|
||||
Make sure you don’t select the drive with your Windows 10 OS.
|
||||
|
||||
#. Go through remaining steps to complete the installation.
|
||||
|
||||
#. Reboot.
|
||||
|
||||
#. During the BIOS POST stage, press :kbd:`F10`, or the proper F-key for your
|
||||
system, to launch the :guilabel:`Boot Menu`.
|
||||
|
||||
.. figure:: ../../_figures/multi-boot/dual-boot-win-03.png
|
||||
:scale: 85%
|
||||
:alt: Boot menu
|
||||
|
||||
Figure 4: Boot menu
|
||||
|
||||
#. In the :guilabel:`Boot Menu`, use the arrow to select the
|
||||
:guilabel:`Linux bootloader` as boot device.
|
||||
|
||||
Some BIOSes do not support listing multiple partitions. In this case,
|
||||
it will only show one bootable partition.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you don't want to use the BIOS boot menu each time to select an OS,
|
||||
follow the next section.
|
||||
|
||||
.. _advanced-systemd-boot:
|
||||
|
||||
Advanced: Use systemd-boot to boot Windows 10 OS and |CL|
|
||||
*********************************************************
|
||||
|
||||
If you prefer not to use your BIOS to load the :guilabel:`Boot Menu` and select an OS to boot, you can make :command:`systemd-boot` the default bootloader and add Windows 10 OS to the boot list. This option is also a workaround for BIOSes that don’t support booting more than one partition.
|
||||
|
||||
#. Boot up the |CL| installer.
|
||||
|
||||
#. Open a Terminal window and enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
lsblk
|
||||
|
||||
#. Example output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
clrlinux@clr-live~ $ lsblk
|
||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
|
||||
loop0 7:0 0 2.3G 1 loop
|
||||
sda 8:0 0 335.4G 0 disk
|
||||
├─sda1 8:1 0 450M 0 part
|
||||
├─sda2 8:2 0 100M 0 part
|
||||
├─sda3 8:3 0 16M 0 part
|
||||
├─sda4 8:4 0 286G 0 part
|
||||
├─sda5 8:5 0 143M 0 part
|
||||
├─sda6 8:6 0 244M 0 part
|
||||
└─sda7 8:7 0 48.5G 0 part
|
||||
sdb 8:16 1 7G 0 disk
|
||||
├─sdb1 8:17 1 2.5G 0 part
|
||||
└─sdb2 8:18 1 100M 0 part
|
||||
|
||||
#. The example output shows:
|
||||
|
||||
* /dev/sda2 is the EFI system partition created by Windows
|
||||
* /dev/sda4 is the primary Windows partition
|
||||
* /dev/sda5 is the EFI system partition created by Clear Linux
|
||||
* /dev/sda7 is the Clear Linux root partition
|
||||
|
||||
#. Create mount points.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir /mnt/windows-efi
|
||||
|
||||
sudo mkdir /mnt/clearlinux
|
||||
|
||||
#. Mount the EFI system partition for Windows 10 OS.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mount /dev/sda2 /mnt/windows-efi
|
||||
|
||||
#. Mount the |CL| root partition and its EFI system partition.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mount /dev/sda7 /mnt/clearlinux
|
||||
|
||||
sudo mount /dev/sda5 /mnt/clearlinux/boot
|
||||
|
||||
#. Copy Windows 10 OS bootloader, and other data needed to boot it, to the
|
||||
|CL| EFI system partition.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo cp -r /mnt/windows-efi/EFI/Microsoft/ /mnt/clearlinux/boot/EFI/
|
||||
|
||||
#. Make :command:`systemd-boot` the default bootloader and add Windows 10
|
||||
OS Boot Manager.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo bootctl install --esp-path=/mnt/clearlinux/boot
|
||||
|
||||
#. Add a timeout value to the :command:`systemd-boot`. This allows enough
|
||||
time for you to select your preferred OS from the menu.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo clr-boot-manager set-timeout 20 --path=/mnt/clearlinux
|
||||
|
||||
sudo clr-boot-manager update --path=/mnt/clearlinux
|
||||
|
||||
#. Umount all partitions.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo umount /mnt/windows-efi /mnt/clearlinux/boot /mnt/clearlinux
|
||||
|
||||
#. Reboot
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo reboot
|
||||
|
||||
#. Remove the |CL| installer USB thumb drive.
|
||||
|
||||
#. You should be presented with the :command:`systemd-boot` menu, as shown
|
||||
below.
|
||||
|
||||
.. figure:: ../../_figures/multi-boot/dual-boot-win-04.png
|
||||
:scale: 85%
|
||||
:alt: systemd-boot menu
|
||||
|
||||
Figure 5: systemd-boot menu
|
||||
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
.. _multi-boot:
|
||||
|
||||
Multi-boot |CL-ATTR| with other operating systems
|
||||
#################################################
|
||||
|
||||
| The |CL-PRJ| offers the ability to dual-boot |CL| with Windows\* 10 OS.
|
||||
| More dual-boot and multi-boot use cases will be introduced in the future.
|
||||
|
||||
.. warning::
|
||||
|
||||
Always back up critical data before installing an additional OS on a target system. Some data loss may occur.
|
||||
|
||||
Detailed procedures
|
||||
*******************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
dual-boot-win
|
||||
|
||||
+124
-32
@@ -34,9 +34,29 @@ Prerequisites
|
||||
* A |CL| system with a desktop installed
|
||||
* An NVIDIA device installed
|
||||
|
||||
Install DKMS
|
||||
.. note:: NVIDIA Optimus
|
||||
|
||||
Some systems come with a hybrid graphics configuration for a balanced power
|
||||
and performance profile. This configuration is commonly found on
|
||||
laptops. `NVIDIA Optimus* technology
|
||||
<https://www.geforce.com/hardware/technology/optimus>`_, is designed to
|
||||
allow switching seamlessly between a NVIDIA device and another graphics
|
||||
devices sharing the same display.
|
||||
|
||||
Getting NVIDIA Optimus* on Linux working well with both graphics devices
|
||||
adds an additional level of complexity with platform specific steps and may
|
||||
require additional software. Installation for systems with NVIDIA Optimus*
|
||||
with both graphics devices operating is not covered by the scope of this
|
||||
documentation. As a simple workaround, some systems can disable one of the
|
||||
graphics devices or NVIDIA Optimus* in the system firmware.
|
||||
|
||||
|
||||
Installation
|
||||
************
|
||||
|
||||
Install DKMS
|
||||
============
|
||||
|
||||
The :ref:`Dynamic Kernel Module System (DKMS)
|
||||
<kernel-modules-dkms>` allows the NVIDIA kernel modules to be automatically
|
||||
integrated when kernel updates occur in |CL|.
|
||||
@@ -51,11 +71,8 @@ Install the appropriate DKMS bundle using the instructions below:
|
||||
:start-after: kernel-modules-dkms-install-begin:
|
||||
:end-before: kernel-modules-dkms-install-end:
|
||||
|
||||
Download and install the NVIDIA drivers
|
||||
***************************************
|
||||
|
||||
Download the NVIDIA drivers for Linux
|
||||
=====================================
|
||||
Download the NVIDIA drivers
|
||||
===========================
|
||||
|
||||
#. Identify the NVIDIA GPU model that is installed.
|
||||
|
||||
@@ -65,22 +82,19 @@ Download the NVIDIA drivers for Linux
|
||||
|
||||
#. Go to the `NVIDIA Driver Downloads website`_ . Search for and download the
|
||||
appropriate driver based on the NVIDIA GPU model you have with *Linux
|
||||
64-bit* selected as the Operating System .
|
||||
|
||||
#. Open a terminal and navigate to where the
|
||||
:file:`NVIDIA-Linux-x86_64-<VERSION>.run` file was saved. In this
|
||||
example, it was saved in the Downloads folder.
|
||||
64-bit* selected as the Operating System.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/Downloads/
|
||||
wget https://download.nvidia.com/XFree86/Linux-x86_64/<VERSION>/NVIDIA-Linux-x86_64-<VERSION>.run
|
||||
|
||||
#. Make the :file:`NVIDIA-Linux-x86_64-<VERSION>.run` file executable.
|
||||
If you already know the appropriate driver version for your device, you can
|
||||
also obtain a download link directly from one of the links below:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
chmod +x :file:`NVIDIA-Linux-x86_64-<VERSION>.run`
|
||||
- https://www.nvidia.com/en-us/drivers/unix/
|
||||
- https://download.nvidia.com/XFree86/Linux-x86_64/
|
||||
|
||||
|
||||
Disable the nouveau driver
|
||||
==========================
|
||||
|
||||
@@ -146,12 +160,19 @@ Install the NVIDIA drivers
|
||||
installation progress. Switch to a secondary virtual terminal by pushing
|
||||
:command:`CTRL + ALT + F2` or remotely login over SSH.
|
||||
|
||||
#. Navigate to the directory where the NVIDIA installer was downloaded.
|
||||
#. Navigate to the directory where the NVIDIA installer was downloaded. In
|
||||
this example, it was saved in the :file:`Downloads` folder.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/Downloads/
|
||||
|
||||
#. Make the :file:`NVIDIA-Linux-x86_64-<VERSION>.run` file executable.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
chmod +x NVIDIA-Linux-x86_64-<VERSION>.run
|
||||
|
||||
#. Run the installer with the advanced options below.
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -192,17 +213,25 @@ Install the NVIDIA drivers
|
||||
|
||||
sudo swupd repair --quick --bundles=lib-opengl
|
||||
|
||||
.. note::
|
||||
.. warning::
|
||||
|
||||
The NVIDIA software places some files under the :file:`/usr` subdirectory
|
||||
that are not managed by |CL| and conflict with the |CL| stateless design.
|
||||
Although a limited version of :command:`swupd repair` is run above,
|
||||
other uses of the :command:`swupd repair` command should be avoided
|
||||
with the proprietary NVIDIA drivers installed.
|
||||
|
||||
Although a limited version of :command:`swupd repair` is run above,
|
||||
other uses of the :command:`swupd repair` command should be avoided
|
||||
with the proprietary NVIDIA drivers installed.
|
||||
The NVIDIA software places some files under the :file:`/usr` subdirectory
|
||||
that are not managed by |CL| and conflict with the |CL| stateless design.
|
||||
|
||||
Updating the NVIDIA drivers
|
||||
***************************
|
||||
#. Optional: Create a link for the nvidia-settings desktop entry to
|
||||
:file:`~/.local/share` so that it appears in the launcher for easy access.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ln -sv /opt/nvidia/share/applications/nvidia-settings.desktop $HOME/.local/share
|
||||
|
||||
|
||||
Updating
|
||||
********
|
||||
|
||||
The proprietary NVIDIA drivers are installed manually outside of
|
||||
:ref:`swupd <swupd-guide>` and must be updated manually when needed.
|
||||
@@ -211,7 +240,7 @@ Updating the NVIDIA drivers follows the same steps as initial installation,
|
||||
however the desktop environment must first be stopped so that the drivers are
|
||||
not in use.
|
||||
|
||||
#. Follow the steps in the `Download the NVIDIA Drivers for Linux`_ section
|
||||
#. Follow the steps in the `Download the NVIDIA drivers`_ section
|
||||
to get the latest NVIDIA drivers.
|
||||
|
||||
#. Temporarily set the default boot target to the *multi-user*, which is
|
||||
@@ -243,8 +272,8 @@ not in use.
|
||||
|
||||
flatpak update
|
||||
|
||||
Uninstalling the NVIDIA drivers
|
||||
*******************************
|
||||
Uninstallation
|
||||
**************
|
||||
|
||||
The NVIDIA drivers and associated software can be uninstalled and nouveau
|
||||
driver restored with the instructions in this section.
|
||||
@@ -261,12 +290,25 @@ driver restored with the instructions in this section.
|
||||
|
||||
sudo rm /etc/X11/xorg.conf.d/nvidia-files-opt.conf
|
||||
|
||||
#. Run the :command:`sudo /opt/nvidia/bin/nvidia-uninstall`
|
||||
#. Remove the nvidia-settings desktop entry file if it was linked to
|
||||
:file:`~/.local/share`.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
unlink -v $HOME/.local/share/nvidia-settings.desktop
|
||||
|
||||
|
||||
#. Run the :command:`nvidia-uninstall` command.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo /opt/nvidia/bin/nvidia-uninstall
|
||||
|
||||
#. Follow the prompts on the screen and reboot the system.
|
||||
|
||||
Debugging installation of NVIDIA drivers
|
||||
****************************************
|
||||
|
||||
Troubleshooting
|
||||
***************
|
||||
|
||||
* The NVIDIA driver places installer and uninstaller logs under
|
||||
:file:`/var/log/nvidia-install` and :file:`/var/log/nvidia-uninstall`.
|
||||
@@ -278,8 +320,56 @@ Debugging installation of NVIDIA drivers
|
||||
installation files into a directory named
|
||||
:file:`NVIDIA-Linux-x86_64-<VERSION>`.
|
||||
|
||||
|
||||
Brightness control
|
||||
==================
|
||||
|
||||
If you can't control the screen brightness with the NVIDIA driver installed,
|
||||
try one of the solutions below:
|
||||
|
||||
- Add a kernel parameter *acpi_osi=* which disables the ACPI Operating System
|
||||
Identification function. Some system firmware may manipulate brightness
|
||||
control keys based on the reported operating system. Disabling the
|
||||
identification mechanism can cause the system firmware to expose brightness
|
||||
controls that are recognizable in Linux.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo mkdir -p /etc/kernel/cmdline.d
|
||||
echo "acpi_osi=" | sudo tee /etc/kernel/cmdline.d/acpi-backlight.conf
|
||||
sudo clr-boot-manager update
|
||||
|
||||
|
||||
|
||||
- Add a kernel parameter for the nvidia driver:
|
||||
*NVreg_EnableBacklightHandler=1*. This handler overrides the ACPI-based one
|
||||
provided by the video.ko kernel module. This option is available with NVIDIA
|
||||
driver version 387.22 and above.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo mkdir -p /etc/kernel/cmdline.d
|
||||
echo "nvidia.NVreg_EnableBacklightHandler=1" | sudo tee /etc/kernel/cmdline.d/nvidia-backlight.conf
|
||||
sudo clr-boot-manager update
|
||||
|
||||
|
||||
- Add the *EnableBrightnessControl=1* options to the *Device*
|
||||
section of your xorg config. Below is an example:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo mkdir -p /etc/X11/xorg.conf.d/
|
||||
|
||||
sudo tee /etc/X11/xorg.conf.d/nvidia-brightness.conf > /dev/null <<'EOF'
|
||||
Section "Device"
|
||||
Identifier "Device0"
|
||||
Driver "nvidia"
|
||||
Option "RegistryDwords" "EnableBrightnessControl=1"
|
||||
EndSection
|
||||
EOF
|
||||
|
||||
Additional resources
|
||||
********************
|
||||
====================
|
||||
|
||||
* `Why aren't the NVIDIA Linux drivers open source? <https://nvidia.custhelp.com/app/answers/detail/a_id/1849/kw/Linux>`_
|
||||
|
||||
@@ -290,3 +380,5 @@ Additional resources
|
||||
.. _`nouveau project`: https://nouveau.freedesktop.org/wiki/
|
||||
|
||||
.. _`NVIDIA Driver Downloads website`: https://www.nvidia.com/download/index.aspx
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,290 @@
|
||||
.. _openvino:
|
||||
|
||||
OpenVINO™ for Deep Learning
|
||||
###########################
|
||||
|
||||
This tutorial shows how to install OpenVINO™ on |CL-ATTR|, run an
|
||||
OpenVINO sample application for image classification, and run a benchmark_app
|
||||
for estimating inference performance---using Squeezenet 1.1.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
* |CL| installed on the host OS
|
||||
|
||||
Install OpenVINO
|
||||
****************
|
||||
|
||||
OpenVINO in |CL| offers pre-built OpenVINO sample applications with which
|
||||
developers can try inferencing immediately.
|
||||
|
||||
#. In |CL| OpenVINO is included in the :command:`computer-vision-basic`
|
||||
bundle. To install OpenVINO, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add computer-vision-basic
|
||||
|
||||
#. OpenVINO Inference Engine libraries are located in :file:`/usr/lib64/`
|
||||
To view one added package, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ls /usr/lib64/libinference_engine.so
|
||||
|
||||
If bundle installation is successful, the output shows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
/usr/lib64/libinference_engine.so
|
||||
|
||||
#. To view the OpenVINO Model Optimizer, enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
ls /usr/share/openvino/model-optimizer
|
||||
|
||||
#. To view the OpenVINO sample application Executables, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ls /usr/bin/benchmark_app \
|
||||
/usr/bin/classification_sample_async \
|
||||
/usr/bin/hello_classification \
|
||||
/usr/bin/hello_nv12_input_classification \
|
||||
/usr/bin/hello_query_device \
|
||||
/usr/bin/hello_reshape_ssd \
|
||||
/usr/bin/object_detection_sample_ssd \
|
||||
/usr/bin/speech_sample \
|
||||
/usr/bin/style_transfer_sample \
|
||||
|
||||
.. note::
|
||||
|
||||
If bundle installation is successful, the above files should appear.
|
||||
|
||||
#. To view the pre-built OpenVINO sample application source code, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ls /usr/share/doc/inference_engine/samples
|
||||
|
||||
In the next section, you learn how to use an OpenVINO sample application.
|
||||
|
||||
Run OpenVINO sample application
|
||||
*******************************
|
||||
|
||||
After installing OpenVINO on |CL|, you need a model against which to test.
|
||||
In this example, we use the public squeezenet 1.1 model for image
|
||||
classification. Test results vary based on the system used.
|
||||
|
||||
Use model to test
|
||||
=================
|
||||
|
||||
#. If you don’t have any model, you can download an
|
||||
**intel_model** or a public model using OpenVINO Model Downloader.
|
||||
|
||||
- Check the list of public models you can download from
|
||||
:file:`/usr/share/open_model_zoo/models/public`
|
||||
|
||||
- Check the list of Intel® models you can download from
|
||||
:file:`/usr/share/open_model_zoo/intel_models`
|
||||
|
||||
#. View the location of OpenVINO Model Downloader:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd /usr/share/open_model_zoo/tools/downloader
|
||||
|
||||
#. In general, download models with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python3 downloader.py --name <model_name> -o <downloading_path>
|
||||
|
||||
.. note::
|
||||
|
||||
* Where :file:`<model_name>` is the one you chose from previous step
|
||||
|
||||
* Where :file:`<downloading_path>` is your project directory
|
||||
|
||||
#. For this example, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python3 downloader.py --name squeezenet1.1 -o $HOME/.
|
||||
|
||||
#. After running this command, the model appears as downloading at your
|
||||
:file:`$HOME/classification/squeezenet/1.1/caffe` as follows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
###############|| Downloading topologies ||###############
|
||||
|
||||
========= Downloading /$HOME/classification/squeezenet/1.1/caffe/squeezenet1.1.caffemodel
|
||||
... 100%, 4834 KB, 2839 KB/s, 1 seconds passed
|
||||
|
||||
...
|
||||
|
||||
Convert model to IR format
|
||||
==========================
|
||||
|
||||
#. As necessary, follow the instruction on :ref:`convert-dl-models`
|
||||
to convert deep learning models.
|
||||
|
||||
#. Navigate to the model:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd $HOME/classification/squeezenet/1.1/caffe
|
||||
|
||||
#. Enter the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python3 /usr/share/openvino/model-optimizer/mo.py --input_model squeezenet1.1.caffemodel
|
||||
|
||||
|
||||
The output will show these files being generated:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
squeezenet1.1.xml
|
||||
|
||||
squeezenet1.1.bin
|
||||
|
||||
#. Finally, enter :command:`ls` to view the newly added model and files.
|
||||
|
||||
Run image classification
|
||||
========================
|
||||
|
||||
This sample application demonstrates how to run the Image Classification in asynchronous mode on supported devices. In this example, we use the image of a specific type of automobile to test the inference engine. Squeezenet 1.1 is designed to perform image classification and has been trained on the `ImageNet`_ database.
|
||||
|
||||
#. We provide an image of an automobile, shown in Figure 1. For ease of use,
|
||||
save this image into the :file:`classification` model directory.
|
||||
|
||||
.. figure:: ../_figures/openvino/automobile.png
|
||||
:height: 375 px
|
||||
:width: 500 px
|
||||
:scale: 100 %
|
||||
:alt: Photo by Goh Rhy Yan on Unsplash
|
||||
|
||||
Figure 1: Photo by Goh Rhy Yan on Unsplash
|
||||
|
||||
#. To execute the sample application enter the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
classification_sample_async -i <path_to_image> -m <path_to_model_ir> -d <device>
|
||||
|
||||
.. note::
|
||||
|
||||
* Where :file:`<path_to_image>` is the image that you selected
|
||||
|
||||
* Where :file:`<path_to_model_ir>` is the path to the IR model file
|
||||
|
||||
* Where :file:`<device>` is your choice of CPU, GPU, etc.
|
||||
|
||||
#. In this case, we replace the :file:`<path_to_image>` with the previously
|
||||
saved image for CPU inferencing.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
classification_sample_async -i ./automobile.png -m squeezenet1.1.xml
|
||||
|
||||
.. note::
|
||||
|
||||
If you do not specify the :file:`device`, the CPU is used by default.
|
||||
|
||||
#. The results show the highest probability is 67% for a sports car.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
classid probability
|
||||
------- -----------
|
||||
817 0.6717085
|
||||
511 0.1611409
|
||||
|
||||
+-----------------------+-----------------------------------+
|
||||
|:command:`classid` 817 | :command:`sports car, sport car` |
|
||||
+-----------------------+-----------------------------------+
|
||||
|:command:`classid` 511 |:command:`convertible` |
|
||||
+-----------------------+-----------------------------------+
|
||||
|
||||
.. note:
|
||||
|
||||
Label definitions are provided by `ImageNet`_.
|
||||
|
||||
#. Next, add :command:`-d GPU` to the end of the above command for GPU
|
||||
inferencing.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
classification_sample_async -i ./automobile.png -m squeezenet1.1.xml -d GPU
|
||||
|
||||
Run benchmark_app
|
||||
*****************
|
||||
|
||||
This sample application demonstrates how to use benchmark application to
|
||||
estimate deep learning inference **performance** on supported devices.
|
||||
We use the same image of an automobile, Figure 1, from the previous section.
|
||||
|
||||
#. To execute this sample application, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
benchmark_app -i <path_to_image> -m <path_to_model> -d <device>
|
||||
|
||||
.. note::
|
||||
|
||||
* Where :file:`<path_to_image>` is the image that you selected
|
||||
|
||||
* Where :file:`<path_to_model_ir>` is the path to the IR model file
|
||||
|
||||
* Where :file:`<device>` is local your choice of CPU, GPU, etc.
|
||||
|
||||
#. Change directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd $HOME/classification/squeezenet/1.1/caffe
|
||||
|
||||
#. Enter the following command for CPU inferencing.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
benchmark_app -i ./automobile.png -m squeezenet1.1.xml
|
||||
|
||||
#. For the CPU, the results show a :guilabel:`Throughput` of 243.202 FPS.
|
||||
|
||||
.. code-block:: console
|
||||
:linenos:
|
||||
:emphasize-lines: 4
|
||||
|
||||
Count: 1464 iterations
|
||||
Duration: 60196.8 ms
|
||||
Latency: 164.104 ms
|
||||
Throughput: 243.202 FPS
|
||||
|
||||
#. Next, add :command:`-d GPU` to the end of the same command for GPU
|
||||
inferencing.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
benchmark_app -i ./automobile.png -m squeezenet1.1.xml -d GPU
|
||||
|
||||
#. For the GPU, the results show a :guilabel:`Throughput` of 372.677 FPS.
|
||||
|
||||
.. code-block:: console
|
||||
:linenos:
|
||||
:emphasize-lines: 4
|
||||
|
||||
Count: 2240 iterations
|
||||
Duration: 60105.7 ms
|
||||
Latency: 107.554 ms
|
||||
Throughput: 372.677 FPS
|
||||
|
||||
.. _ImageNet: http://image-net.org/
|
||||
+51
-48
@@ -4,21 +4,22 @@ Proxy configuration
|
||||
###################
|
||||
|
||||
This tutorial shows you how to configure your system for use behind an
|
||||
outbound proxy to access the Internet.
|
||||
outbound proxy to access the Internet.
|
||||
|
||||
|CL| applications already benefit from the :ref:`autoproxy`
|
||||
feature.
|
||||
|CL-ATTR| applications already benefit from the :ref:`autoproxy`
|
||||
feature.
|
||||
|
||||
.. contents::
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
This tutorial assumes you have installed |CL| on your host system.
|
||||
For detailed instructions on installing |CL| on a bare metal system, visit
|
||||
the :ref:`bare metal installation guide <bare-metal-install-desktop>`.
|
||||
* You have installed |CL| on your host system.
|
||||
|
||||
For detailed instructions on installing |CL| on a bare metal system, visit
|
||||
the :ref:`bare metal installation guide <bare-metal-install-desktop>`.
|
||||
|
||||
Shells and programs in a desktop session
|
||||
****************************************
|
||||
@@ -30,67 +31,69 @@ Add the following to your ~/.bashrc:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export http_proxy=http://your.http-proxy.url:port
|
||||
export https_proxy=http://your.https-proxy.url:port
|
||||
export ftp_proxy=http://your.ftp-proxy.url:port
|
||||
export socks_proxy=http://your.socks-proxy.url:port
|
||||
export no_proxy=".your-company-domain.com,localhost"
|
||||
export HTTP_PROXY=$http_proxy
|
||||
export HTTPS_PROXY=$https_proxy
|
||||
export FTP_PROXY=$ftp_proxy
|
||||
export SOCKS_PROXY=$socks_proxy
|
||||
export NO_PROXY=$no_proxy
|
||||
export http_proxy=http://your.http-proxy.url:port
|
||||
export https_proxy=http://your.https-proxy.url:port
|
||||
export ftp_proxy=http://your.ftp-proxy.url:port
|
||||
export socks_proxy=http://your.socks-proxy.url:port
|
||||
export no_proxy=".your-company-domain.com,localhost"
|
||||
export HTTP_PROXY=$http_proxy
|
||||
export HTTPS_PROXY=$https_proxy
|
||||
export FTP_PROXY=$ftp_proxy
|
||||
export SOCKS_PROXY=$socks_proxy
|
||||
export NO_PROXY=$no_proxy
|
||||
|
||||
wget
|
||||
****
|
||||
====
|
||||
|
||||
Run this command to enable downloading from websites from the terminal:
|
||||
Run the following command to enable downloading from websites from the terminal:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
echo >> ~/.wgetrc <<EOF
|
||||
http_proxy = your.http-proxy.url:port
|
||||
https_proxy = your.https-proxy.url:port
|
||||
ftp_proxy = your.http-proxy.url:port
|
||||
no_proxy = your-company-domain.com, localhost
|
||||
EOF
|
||||
echo >> ~/.wgetrc <<EOF
|
||||
http_proxy = your.http-proxy.url:port
|
||||
https_proxy = your.https-proxy.url:port
|
||||
ftp_proxy = your.http-proxy.url:port
|
||||
no_proxy = your-company-domain.com, localhost
|
||||
EOF
|
||||
|
||||
System service (Docker)
|
||||
***********************
|
||||
System service (Docker\*)
|
||||
=========================
|
||||
|
||||
For Docker (and other services that use systemd), you can follow these steps to configure and check proxy settings:
|
||||
For Docker (and other services that use systemd), follow these steps to
|
||||
configure and check proxy settings.
|
||||
|
||||
.. note::
|
||||
|
||||
Be sure to use :command:`sudo`, as you will need elevated permissions.
|
||||
Use :command:`sudo`, as you will need elevated permissions.
|
||||
|
||||
#. Create :file:`/etc/systemd/system/docker.service.d` directory to host
|
||||
#. Create the :file:`/etc/systemd/system/docker.service.d` directory to host
|
||||
configuration information for the Docker service.
|
||||
|
||||
#. Create :file:`/etc/systemd/system/docker.service.d/http-proxy.conf` and add:
|
||||
#. Create the :file:`/etc/systemd/system/docker.service.d/http-proxy.conf`
|
||||
and add the following lines:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
[Service]
|
||||
Environment="HTTP_PROXY=http://your.http-proxy.url:port/"
|
||||
Environment="HTTPS_PROXY=http://your.https-proxy.url:port/"
|
||||
[Service]
|
||||
Environment="HTTP_PROXY=http://your.http-proxy.url:port/"
|
||||
Environment="HTTPS_PROXY=http://your.https-proxy.url:port/"
|
||||
|
||||
#. Load the changes and restart the service:
|
||||
#. Load the changes and restart the service.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart docker
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart docker
|
||||
|
||||
#. Verify that changes have loaded:
|
||||
#. Verify that changes have loaded.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl show --property=Environment docker
|
||||
systemctl show --property=Environment docker
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: console
|
||||
|
||||
Environment=HTTP_PROXY=http://your.http-proxy.url:port/ HTTPS_PROXY=http://your.https-proxy.url:port/
|
||||
Environment=HTTP_PROXY=http://your.http-proxy.url:port/ HTTPS_PROXY=http://your.https-proxy.url:port/
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -104,12 +107,12 @@ Add the following to your :file:`~/.ssh/config`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
host github.com
|
||||
port 22
|
||||
host github.com
|
||||
port 22
|
||||
user git
|
||||
ProxyCommand connect-proxy -S your.ssh-proxy.url:port %h %p
|
||||
|
||||
.. note::
|
||||
|
||||
Though netcat is included with Clear Linux, it is not the BSD version,
|
||||
which is the one usually used to enable git over ssh.
|
||||
Though netcat is included with |CL|, it is not the BSD version,
|
||||
which is the one usually used to enable git over ssh.
|
||||
+46
-36
@@ -3,45 +3,53 @@
|
||||
Redis\*
|
||||
#######
|
||||
|
||||
Redis is an in-memory key:value store designed for quick lookups, accessible
|
||||
over the network. In this tutorial, you'll install redis and launch a
|
||||
redis-server on |CL|, plus learn a few basic redis commands. We also invite
|
||||
you to pull our `Clear Linux Redis instance`_ on dockerhub\* for application
|
||||
or infrastructure development.
|
||||
|
||||
While the `redis data structure store`_ can serve as a NoSQL database for a Web application, it's also easy to integrate in an existing stack. For example, you could use the Redis caching layer for real-time responses on a leaderboard in a gaming app. Redis offers many client libraries with language-specific bindings for Python, Perl, Ruby, and more.
|
||||
In this tutorial, you'll install :abbr:`Redis (REmote DIctionary Server)`
|
||||
and launch a `Redis-server` on |CL-ATTR|. We invite you to pull our
|
||||
`Clear Linux Redis instance`_ on dockerhub\* for application or
|
||||
infrastructure development.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
Redis is an in-memory key:value store designed for quick lookups, accessible over a network. While the `redis data structure store`_ can serve
|
||||
as a NoSQL database for a web application, it's also easy to integrate into an
|
||||
existing stack. For example, you could use the Redis caching layer for
|
||||
real-time responses on a leaderboard in a gaming app. Redis offers many client
|
||||
libraries with language-specific bindings for Python\*, Perl\*, Ruby, and more.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
* Install the `redis-native` bundle in |CL|
|
||||
* Install the `containers-basic` bundle in |CL| (only required in Example 2)
|
||||
|
||||
Install the redis bundle
|
||||
* Install the :command:`redis-native` bundle in |CL|
|
||||
* Install the :command:`containers-basic` bundle in |CL| (only required in
|
||||
Example 2)
|
||||
|
||||
Install the Redis bundle
|
||||
************************
|
||||
|
||||
In |CL|, find redis in the `redis-native` bundle.
|
||||
In |CL|, find Redis in the :command:`redis-native` bundle.
|
||||
|
||||
#. Open a Terminal and login as an administrative user.
|
||||
#. Open a terminal and login as an administrative user.
|
||||
|
||||
#. Add :file:`redis-native`.
|
||||
#. Add :command:`redis-native`.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add redis-native
|
||||
sudo swupd bundle-add redis-native
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
If the bundle already exists, no action is required.
|
||||
If the bundle already exists, no action is required.
|
||||
|
||||
Start the redis-server
|
||||
Start the Redis-server
|
||||
**********************
|
||||
|
||||
A `systemd` service unit is available to control the redis server.
|
||||
By default, redis runs on port 6379.
|
||||
A :command:`systemd` service unit is available to control the Redis-server.
|
||||
By default, Redis runs on port 6379.
|
||||
|
||||
#. Start the service.
|
||||
|
||||
@@ -51,15 +59,15 @@ By default, redis runs on port 6379.
|
||||
|
||||
.. note::
|
||||
|
||||
To stop redis run :command:`systemctl stop redis`.
|
||||
To stop Redis, run :command:`systemctl stop redis`.
|
||||
|
||||
#. Assure the service is running.
|
||||
#. Confirm the service is running.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl status redis
|
||||
|
||||
#. Verify the redis-server sends a reply.
|
||||
#. Verify that the Redis-server sends a reply.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -69,24 +77,25 @@ By default, redis runs on port 6379.
|
||||
|
||||
Expected output: `PONG`.
|
||||
|
||||
#. Optional: If you wish to apply advanced configuration, copy the
|
||||
#. Optional: If you wish to apply the advanced configuration, copy the
|
||||
`redis.conf` into /etc/ directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo cp /usr/share/defaults/etc/redis.conf /etc/
|
||||
|
||||
The redis-server is now ready to use on |CL|. Try some examples below.
|
||||
The Redis-server is now ready to use on |CL|. Try some of the examples shown
|
||||
below.
|
||||
|
||||
Example 1: Use the redis-cli and try commands
|
||||
*********************************************
|
||||
Example 1: Use the redis-cli and commands
|
||||
*****************************************
|
||||
|
||||
One advantage of redis over other NoSQL databases is that developers can
|
||||
One advantage of Redis over other NoSQL databases is that developers can
|
||||
easily access data structures like lists, sets, sorted sets, strings, and
|
||||
hashes using collection operations commands similar to those found in many
|
||||
programming languages. These exercises are inspired by `try redis io`_.
|
||||
|
||||
After your `redis-server` is running, try some basic commands.
|
||||
After your Redis-server is running, try some basic commands.
|
||||
|
||||
#. Enter the `redis-cli`. It provides syntax suggestions as you type.
|
||||
|
||||
@@ -94,7 +103,8 @@ After your `redis-server` is running, try some basic commands.
|
||||
|
||||
redis-cli
|
||||
|
||||
#. SET key to hold string value. In the set create connections and increment.
|
||||
#. :command:`SET` a key to hold a string value. In the set, create connections
|
||||
and increment.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -137,7 +147,7 @@ After your `redis-server` is running, try some basic commands.
|
||||
|
||||
RPUSH friends "Mary"
|
||||
|
||||
#. Modify `friends` list, using a common slice method with a 0-index.
|
||||
#. Modify the `friends` list, using a common slice method with a 0-index.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -159,8 +169,8 @@ After your `redis-server` is running, try some basic commands.
|
||||
|
||||
LLEN friends
|
||||
|
||||
#. Consider using a hash, a very useful data type, which maps string fields
|
||||
and string values, offering multiple lookup methods.
|
||||
#. Consider using a hash, which maps string fields and string values, and
|
||||
offers multiple lookup methods.
|
||||
|
||||
Enter many user key:values with `HMSET`. Then try `HGET` and `HGETALL`.
|
||||
|
||||
@@ -181,8 +191,8 @@ After your `redis-server` is running, try some basic commands.
|
||||
HGETALL user:1000
|
||||
|
||||
|
||||
Example 2: Run the |CL| redis docker image
|
||||
******************************************
|
||||
Example 2: Run the |CL| Redis Docker\* image
|
||||
********************************************
|
||||
|
||||
We also provide a `Clear Linux Redis instance`_, which is
|
||||
updated continuously and maintained by |CL| development.
|
||||
@@ -204,7 +214,7 @@ Next Steps
|
||||
|
||||
* Follow the `redis quickstart tutorial`_ to expand potential uses.
|
||||
|
||||
* Learn to :ref:`docker`.
|
||||
* Learn how to use :ref:`docker`.
|
||||
|
||||
.. _try redis io: https://try.redis.io/
|
||||
|
||||
|
||||
@@ -5,9 +5,13 @@ Samba\* as a client
|
||||
|
||||
This tutorial explains how to access an existing shared drive on
|
||||
Windows\* via Server Message Block (SMB) / Common Internet File System (CIFS)
|
||||
from the |CL| GNOME desktop. CIFS filesystem is generally used to access
|
||||
from the |CL| GNOME\* desktop. A CIFS filesystem is generally used to access
|
||||
shared storage locations, or share files.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
@@ -59,7 +63,7 @@ Connect to Windows shared location with Nautilus
|
||||
|
||||
#. Select :guilabel:`Connect`.
|
||||
|
||||
#. The server will request authentication, as shown in Figure 3.
|
||||
The server requests authentication, as shown in Figure 3.
|
||||
|
||||
.. figure:: /_figures/samba/smb-desktop-3.png
|
||||
:scale: 100%
|
||||
|
||||
+32
-24
@@ -4,20 +4,27 @@ Samba\* as a host
|
||||
#################
|
||||
|
||||
This tutorial describes how to enable simple file sharing from a system
|
||||
running |CL-ATTR| to a Windows machine using Samba. For more advanced sharing,
|
||||
refer to the `Samba guide`_.
|
||||
running |CL-ATTR| to a Windows\* computer using Samba. For more advanced
|
||||
sharing, refer to the `Samba guide`_.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
This tutorial assumes you have installed |CL| on your host system. For
|
||||
detailed instructions, follow the steps in :ref:`bare-metal-install-desktop`.
|
||||
* |CL| is installed on your host system.
|
||||
|
||||
Before you install any new packages, update |CL| with the following command:
|
||||
For detailed instructions, follow the steps in
|
||||
:ref:`bare-metal-install-desktop`.
|
||||
|
||||
.. code-block:: bash
|
||||
* Before you install any new packages, update |CL| with the following
|
||||
command:
|
||||
|
||||
sudo swupd update
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd update
|
||||
|
||||
|
||||
Set up file sharing
|
||||
@@ -29,7 +36,7 @@ Set up file sharing
|
||||
|
||||
sudo -s
|
||||
|
||||
#. Add the storage-utils bundle, which includes the Samba binaries.
|
||||
#. Add the :command:`storage-utils` bundle, which includes the Samba binaries.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -37,20 +44,21 @@ Set up file sharing
|
||||
|
||||
.. note::
|
||||
|
||||
The os-clr-on-clr bundle also includes the Samba binaries.
|
||||
The :command:`os-clr-on-clr` bundle also includes the Samba binaries.
|
||||
|
||||
#. Create a configuration file called :file:`/etc/samba/smb.conf`. In this
|
||||
example, `[Downloads]` enables a folder share with a specific user.
|
||||
`[Documents]` enables a folder share with any user. The example assumes that a
|
||||
user account `clearlinuxuser` already exists.
|
||||
#. Create a configuration file named :file:`/etc/samba/smb.conf`. In this
|
||||
example, :envvar:`[Downloads]` enables a folder share with a specific user.
|
||||
:envvar:`[Documents]` enables a folder share with any user. The example
|
||||
assumes that the user account :envvar:`clearlinuxuser` already exists.
|
||||
|
||||
If `valid users` is not specified, then anyone with a user account on the
|
||||
machine and with their Samba password already set can access the folder.
|
||||
However, the account is only able to access files and folders for which
|
||||
they have appropriate permissions.
|
||||
If :envvar:`valid users` is not specified, then anyone with a user account
|
||||
on the machine and with their Samba password already set can access the
|
||||
folder. However, the account is only able to access files and folders for
|
||||
which they have appropriate permissions.
|
||||
|
||||
Use :command:`chown` or :command:`chmod` to change either the owner of the
|
||||
file or the permissions to allow other users to access the file.
|
||||
Use either :command:`chown` to change the owner of the file or use
|
||||
:command:`chmod` to change the permissions to allow other users to access
|
||||
the file.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -78,17 +86,17 @@ Set up file sharing
|
||||
|
||||
#. Use :command:`smbpasswd` to add the initial password for the user
|
||||
account to access the share. Be aware that Samba maintains its own list of
|
||||
passwords for user accounts. The Samba password list can be different than
|
||||
passwords for user accounts. The Samba password list can be different from
|
||||
the password used to log in.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
smbpasswd -a clearlinuxuser
|
||||
|
||||
Setup is complete and a Windows machine on the same network can access the
|
||||
shares. Windows uses the format :file:`\\\\[server IP or hostname]\\folder` to
|
||||
access shares. Access the shares directly with Windows Explorer or by
|
||||
mapping a network drive.
|
||||
The setup is now complete and a Windows machine on the same network can access
|
||||
the shares. Windows uses the format
|
||||
:file:`\\\\[server IP or hostname]\\folder` to access shares. Access the shares
|
||||
directly with Windows Explorer or by mapping a network drive.
|
||||
|
||||
Use the IP address of the |CL| machine for an easy access method. If the
|
||||
|CL| machine is behind an Active Directory domain controller or a DNS server,
|
||||
|
||||
Reference in New Issue
Block a user