diff --git a/.github/workflows/greetings.yml b/.github/workflows/greetings.yml index 4d3398c9..eec14f1e 100644 --- a/.github/workflows/greetings.yml +++ b/.github/workflows/greetings.yml @@ -9,5 +9,5 @@ jobs: - uses: actions/first-interaction@v1 with: repo-token: ${{ secrets.GITHUB_TOKEN }} - issue-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first issue. :thumbsup:' - pr-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first PR. :thumbsup:' + issue-message: 'Welcome to Clear Linux* OS Docs. Thanks for submitting your first issue.' + pr-message: 'Welcome to Clear Linux* OS Docs. Thanks for submitting your first PR.' diff --git a/Makefile b/Makefile index cc811a48..bb3a8c22 100644 --- a/Makefile +++ b/Makefile @@ -34,7 +34,6 @@ clean: rm -rf venv venv: - virtualenv -p python$(PY_VERSION) venv; + virtualenv venv;\ source venv/bin/activate; \ pip3 install -r requirements.txt; - diff --git a/README.rst b/README.rst index 6eca594a..a76ae312 100644 --- a/README.rst +++ b/README.rst @@ -67,6 +67,86 @@ If you want to build the documentation exactly as seen on the website, use ``make py`` followed by ``make htmlall``. This builds some external dependencies and all supported languages. +Use virtualenv +************** + +To develop documentation in a ``virtualenv``, use the ``venv`` target. +The Clear Linux OS documentation make target ``venv`` provides a +simple development environment that ensures that you have the +latest packages and that you manage Python versions separately. Use of the +``virtualenv`` requires **Python 3.6** or higher. For Windows examples below, use Powershell as an Administrator. + +The **virtual environment** uses the same version of Python that was used to **create the virtual environment**. + +Verify ``pip`` is installed. A file path to pip should appear. + +On Clear Linux OS and macOS\*: + +.. code-block:: bash + + which pip + +On Windows\* 10 OS: + +.. code-block:: bash + + pip --version + +If ``pip`` is not installed, install it. + +On Clear Linux OS and macOS: + +.. code-block:: bash + + python3 -m pip install --user --upgrade pip + +On Windows 10 OS: + +.. code-block:: bash + + py -m pip install --upgrade pip + +.. note:: + + This assumes Python was already added to your Windows path. + +Install virtualenv +================== + +Install ``virtualenv``. + +On Clear Linux OS and macOS\*: + +.. code-block:: bash + + python3 -m pip install --user virtualenv + +On Windows 10 OS: + +.. code-block:: bash + + py -m pip install --user virtualenv + +Create the ``virtualenv`` and install the required packages: + +.. code-block:: bash + + make venv + +Activate the ``venv``. + +.. code-block:: bash + + source venv/bin/activate + +Follow `Run the build`_ section to start developing documentation. + +Remove the ``venv`` when finished developing. + +.. code-block:: bash + + deactivate + Additional help *************** @@ -80,7 +160,8 @@ build before building again by running ``make clean``: make clean -This will completely remove the previous build output. +This will completely remove the previous build output, including artifacts +from the `make venv` target when done outside an active venv. Convenience script ================== diff --git a/source/_figures/digitalocean/01-digitalocean-original.png b/source/_figures/digitalocean/01-digitalocean-original.png new file mode 100644 index 00000000..62ab7b27 Binary files /dev/null and b/source/_figures/digitalocean/01-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/01-digitalocean.png b/source/_figures/digitalocean/01-digitalocean.png new file mode 100644 index 00000000..399c81fe Binary files /dev/null and b/source/_figures/digitalocean/01-digitalocean.png differ diff --git a/source/_figures/digitalocean/02-digitalocean-original.png b/source/_figures/digitalocean/02-digitalocean-original.png new file mode 100644 index 00000000..6fc13147 Binary files /dev/null and b/source/_figures/digitalocean/02-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/02-digitalocean.png b/source/_figures/digitalocean/02-digitalocean.png new file mode 100644 index 00000000..2c93fd83 Binary files /dev/null and b/source/_figures/digitalocean/02-digitalocean.png differ diff --git a/source/_figures/digitalocean/03-digitalocean-original.png b/source/_figures/digitalocean/03-digitalocean-original.png new file mode 100644 index 00000000..18765a5b Binary files /dev/null and b/source/_figures/digitalocean/03-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/03-digitalocean.png b/source/_figures/digitalocean/03-digitalocean.png new file mode 100644 index 00000000..313cc6f3 Binary files /dev/null and b/source/_figures/digitalocean/03-digitalocean.png differ diff --git a/source/_figures/digitalocean/04-digitalocean-original.png b/source/_figures/digitalocean/04-digitalocean-original.png new file mode 100644 index 00000000..9cb8a980 Binary files /dev/null and b/source/_figures/digitalocean/04-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/04-digitalocean.png b/source/_figures/digitalocean/04-digitalocean.png new file mode 100644 index 00000000..72f17284 Binary files /dev/null and b/source/_figures/digitalocean/04-digitalocean.png differ diff --git a/source/_figures/digitalocean/05-digitalocean-original.png b/source/_figures/digitalocean/05-digitalocean-original.png new file mode 100644 index 00000000..1166b9fd Binary files /dev/null and b/source/_figures/digitalocean/05-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/05-digitalocean.png b/source/_figures/digitalocean/05-digitalocean.png new file mode 100644 index 00000000..81fe8b1b Binary files /dev/null and b/source/_figures/digitalocean/05-digitalocean.png differ diff --git a/source/_figures/digitalocean/06-digitalocean-original.png b/source/_figures/digitalocean/06-digitalocean-original.png new file mode 100644 index 00000000..58e78cad Binary files /dev/null and b/source/_figures/digitalocean/06-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/06-digitalocean.png b/source/_figures/digitalocean/06-digitalocean.png new file mode 100644 index 00000000..ed914674 Binary files /dev/null and b/source/_figures/digitalocean/06-digitalocean.png differ diff --git a/source/_figures/digitalocean/07-digitalocean-original.png b/source/_figures/digitalocean/07-digitalocean-original.png new file mode 100644 index 00000000..101da446 Binary files /dev/null and b/source/_figures/digitalocean/07-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/07-digitalocean.png b/source/_figures/digitalocean/07-digitalocean.png new file mode 100644 index 00000000..15b694d6 Binary files /dev/null and b/source/_figures/digitalocean/07-digitalocean.png differ diff --git a/source/_figures/digitalocean/08-digitalocean-original.png b/source/_figures/digitalocean/08-digitalocean-original.png new file mode 100644 index 00000000..b5bcb6d1 Binary files /dev/null and b/source/_figures/digitalocean/08-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/08-digitalocean.png b/source/_figures/digitalocean/08-digitalocean.png new file mode 100644 index 00000000..6c336241 Binary files /dev/null and b/source/_figures/digitalocean/08-digitalocean.png differ diff --git a/source/_figures/digitalocean/09-digitalocean-original.png b/source/_figures/digitalocean/09-digitalocean-original.png new file mode 100644 index 00000000..3ee26a9f Binary files /dev/null and b/source/_figures/digitalocean/09-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/09-digitalocean.png b/source/_figures/digitalocean/09-digitalocean.png new file mode 100644 index 00000000..9ecd4231 Binary files /dev/null and b/source/_figures/digitalocean/09-digitalocean.png differ diff --git a/source/_figures/digitalocean/10-digitalocean-original.png b/source/_figures/digitalocean/10-digitalocean-original.png new file mode 100644 index 00000000..6fd2b61a Binary files /dev/null and b/source/_figures/digitalocean/10-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/10-digitalocean.png b/source/_figures/digitalocean/10-digitalocean.png new file mode 100644 index 00000000..a182643d Binary files /dev/null and b/source/_figures/digitalocean/10-digitalocean.png differ diff --git a/source/_figures/digitalocean/11-digitalocean-original.png b/source/_figures/digitalocean/11-digitalocean-original.png new file mode 100644 index 00000000..bed8b160 Binary files /dev/null and b/source/_figures/digitalocean/11-digitalocean-original.png differ diff --git a/source/_figures/digitalocean/11-digitalocean.png b/source/_figures/digitalocean/11-digitalocean.png new file mode 100644 index 00000000..fb24087b Binary files /dev/null and b/source/_figures/digitalocean/11-digitalocean.png differ diff --git a/source/_figures/digitalocean/AA-digitalocean-original-extra.png b/source/_figures/digitalocean/AA-digitalocean-original-extra.png new file mode 100644 index 00000000..b51cb187 Binary files /dev/null and b/source/_figures/digitalocean/AA-digitalocean-original-extra.png differ diff --git a/source/_figures/digitalocean/BB-digitalocean-original-extra.png b/source/_figures/digitalocean/BB-digitalocean-original-extra.png new file mode 100644 index 00000000..6428b3cc Binary files /dev/null and b/source/_figures/digitalocean/BB-digitalocean-original-extra.png differ diff --git a/source/_figures/digitalocean/CC-digitalocean-original-extra.png b/source/_figures/digitalocean/CC-digitalocean-original-extra.png new file mode 100644 index 00000000..9b0d06fd Binary files /dev/null and b/source/_figures/digitalocean/CC-digitalocean-original-extra.png differ diff --git a/source/_figures/digitalocean/Readme.txt b/source/_figures/digitalocean/Readme.txt new file mode 100644 index 00000000..52594a3f --- /dev/null +++ b/source/_figures/digitalocean/Readme.txt @@ -0,0 +1,18 @@ +1) Capture screenshot +2) Open in GIMP 2.10 +3) Select the area of interest +4) Copy the selection; take note of X, Y dimensions of the selection +5) "File" > "New" + - Add 100 extra pixels to X for the "Width" + - Add 100 extra pixels to Y for the "Height" + - Set "Fill with" to "Transparency" +6) Switch from the "Selection" tool to the "Move" tool and move the + the top-left corner of the image to 2 squares down and 2 squares across +7) Right-click the image and select "Layer" > "Anchor Layer" +8) "Filters" > "Decor" > "Light and Shadow" > "Drop Shadow" + - X = 20.0 + - Y = 20.0 + - Radius = 20.0 + - Opacity = 0.2 + + diff --git a/source/_figures/ipxe/ipxe-install-1.png b/source/_figures/ipxe/ipxe-install-1.png new file mode 100644 index 00000000..52bab4b1 Binary files /dev/null and b/source/_figures/ipxe/ipxe-install-1.png differ diff --git a/source/_figures/ipxe/ipxe-install-2.png b/source/_figures/ipxe/ipxe-install-2.png new file mode 100644 index 00000000..cfa3f517 Binary files /dev/null and b/source/_figures/ipxe/ipxe-install-2.png differ diff --git a/source/_figures/stacks/mers-fig-1.png b/source/_figures/stacks/mers-fig-1.png new file mode 100644 index 00000000..799c6fbf Binary files /dev/null and b/source/_figures/stacks/mers-fig-1.png differ diff --git a/source/_figures/stacks/mers-fig-2.png b/source/_figures/stacks/mers-fig-2.png new file mode 100644 index 00000000..cefd8b1d Binary files /dev/null and b/source/_figures/stacks/mers-fig-2.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png b/source/_figures/vmw-player/vmw-player-01.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png rename to source/_figures/vmw-player/vmw-player-01.png diff --git a/source/_figures/vmw-player/vmw-player-02.png b/source/_figures/vmw-player/vmw-player-02.png new file mode 100644 index 00000000..06132d4b Binary files /dev/null and b/source/_figures/vmw-player/vmw-player-02.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png b/source/_figures/vmw-player/vmw-player-03.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png rename to source/_figures/vmw-player/vmw-player-03.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png b/source/_figures/vmw-player/vmw-player-04.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png rename to source/_figures/vmw-player/vmw-player-04.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png b/source/_figures/vmw-player/vmw-player-05.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png rename to source/_figures/vmw-player/vmw-player-05.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png b/source/_figures/vmw-player/vmw-player-06.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png rename to source/_figures/vmw-player/vmw-player-06.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png b/source/_figures/vmw-player/vmw-player-07.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png rename to source/_figures/vmw-player/vmw-player-07.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png b/source/_figures/vmw-player/vmw-player-08.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png rename to source/_figures/vmw-player/vmw-player-08.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png b/source/_figures/vmw-player/vmw-player-09.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png rename to source/_figures/vmw-player/vmw-player-09.png diff --git a/source/_figures/vmw-player/vmw-player-10.png b/source/_figures/vmw-player/vmw-player-10.png new file mode 100644 index 00000000..4eeee082 Binary files /dev/null and b/source/_figures/vmw-player/vmw-player-10.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png b/source/_figures/vmw-player/vmw-player-11.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png rename to source/_figures/vmw-player/vmw-player-11.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png b/source/_figures/vmw-player/vmw-player-17.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png rename to source/_figures/vmw-player/vmw-player-17.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-01.png b/source/_figures/vmw-player/vmw-player-preconf-01.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-01.png rename to source/_figures/vmw-player/vmw-player-preconf-01.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-02.png b/source/_figures/vmw-player/vmw-player-preconf-02.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-02.png rename to source/_figures/vmw-player/vmw-player-preconf-02.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-03.png b/source/_figures/vmw-player/vmw-player-preconf-03.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-03.png rename to source/_figures/vmw-player/vmw-player-preconf-03.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-04.png b/source/_figures/vmw-player/vmw-player-preconf-04.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-04.png rename to source/_figures/vmw-player/vmw-player-preconf-04.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-05.png b/source/_figures/vmw-player/vmw-player-preconf-05.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-05.png rename to source/_figures/vmw-player/vmw-player-preconf-05.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-06.png b/source/_figures/vmw-player/vmw-player-preconf-06.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-06.png rename to source/_figures/vmw-player/vmw-player-preconf-06.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-07.png b/source/_figures/vmw-player/vmw-player-preconf-07.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-07.png rename to source/_figures/vmw-player/vmw-player-preconf-07.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-08.png b/source/_figures/vmw-player/vmw-player-preconf-08.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-08.png rename to source/_figures/vmw-player/vmw-player-preconf-08.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-09.png b/source/_figures/vmw-player/vmw-player-preconf-09.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-09.png rename to source/_figures/vmw-player/vmw-player-preconf-09.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-10.png b/source/_figures/vmw-player/vmw-player-preconf-12.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-10.png rename to source/_figures/vmw-player/vmw-player-preconf-12.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-11.png b/source/_figures/vmw-player/vmw-player-preconf-13.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-11.png rename to source/_figures/vmw-player/vmw-player-preconf-13.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-12.png b/source/_figures/vmw-player/vmw-player-preconf-14.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-12.png rename to source/_figures/vmw-player/vmw-player-preconf-14.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-13.png b/source/_figures/vmw-player/vmw-player-preconf-15.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-13.png rename to source/_figures/vmw-player/vmw-player-preconf-15.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-14.png b/source/_figures/vmw-player/vmw-player-preconf-16.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-14.png rename to source/_figures/vmw-player/vmw-player-preconf-16.png diff --git a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css index 8a68bcb7..4df47ff6 100644 --- a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css +++ b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css @@ -520,3 +520,10 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a } /*End support for multi-column sections*/ + + +/*Add drop shadow to figures*/ + +div.figure.dropshadow img { + box-shadow: 10px 10px 10px LightGray; +} \ No newline at end of file diff --git a/source/get-started/bare-metal-install-desktop.rst b/source/get-started/bare-metal-install-desktop.rst index 5ede7c13..c4793bb7 100644 --- a/source/get-started/bare-metal-install-desktop.rst +++ b/source/get-started/bare-metal-install-desktop.rst @@ -144,8 +144,9 @@ To fulfill minimum installation requirements, complete the * Check marks indicate a selection has been made. - * An Internet connection is required. You may want to launch a browser - prior to installation to verify your Internet connection. + * The installer image contains the default bundles required for + installation. An Internet connection is only required if you install + additional bundles from `Advanced options`_. |CL| Desktop Installer ********************** @@ -650,6 +651,11 @@ Create partitions per requirements in Table 1. - / - *Size depends upon use case/desired bundles.* +Troubleshooting +*************** + +:ref:`erase-lvm-troubleshooting-tip` + .. _Downloads: https://clearlinux.org/downloads diff --git a/source/get-started/bare-metal-install-server.rst b/source/get-started/bare-metal-install-server.rst index aa93bdd6..13316682 100644 --- a/source/get-started/bare-metal-install-server.rst +++ b/source/get-started/bare-metal-install-server.rst @@ -942,4 +942,61 @@ entering :guilabel:`Configure Installation Media`: - Windows\* OS: :command:`diskpart`, then :command:`list disk` - macOS\* platform: :command:`diskutil list` +.. _erase-lvm-troubleshooting-tip: + +Erase LVM Partitions Before Installing |CL| +=========================================== + +If you’re planning to install |CL| on a drive that has LVM partitions, +you must erase them first before using clr-installer. + +Here is an example of a drive (/dev/sda) with LVMs: + +.. code-block:: console + :emphasize-lines: 6-9 + + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT + loop0 7:0 0 627.6M 1 loop + sda 8:0 0 335.4G 0 disk + ├─sda1 8:1 0 200M 0 part + ├─sda2 8:2 0 1G 0 part + └─sda3 8:3 0 334.2G 0 part + ├─LVM-root 252:0 0 70G 0 lvm + ├─LVM-home 252:1 0 248.4G 0 lvm + └─LVM-swap 252:2 0 15.7G 0 lvm + +If you do not erase the LVMs first, you will encounter a clr-installer +error like this: + +.. code-block:: console + + root@clr-live~ # clr-installer + + Please report this crash using GitHub Issues: + https://github.com/clearlinux/clr-installer/issues + + Include the following as attachments to enable diagnosis: + /root/pre-install-clr-installer.yaml + /root/clr-installer.log + + You may need to remove any personal data of concern from the attachments. + The Installer will now exit. + exit status 1 + + Error Trace: + errors.Wrap() + errors/errors.go:91 + storage.makeFs() + storage/ops.go:79 + +The quickest and simplest method to erasing the LVMs is to execute these +commands: + +.. code-block:: bash + + sudo sgdisk -Z /dev/ + sudo partprobe + sudo dmsetup remove_all --force + sudo partprobe + .. _Downloads: https://clearlinux.org/downloads diff --git a/source/get-started/cloud-install/aws-web.rst b/source/get-started/cloud-install/aws-web.rst index 72f7f90d..9d4312c9 100644 --- a/source/get-started/cloud-install/aws-web.rst +++ b/source/get-started/cloud-install/aws-web.rst @@ -279,3 +279,10 @@ instance from running. Congratulations! You are up and running with |CL| on AWS. To see what you can do with your |CL| instance, visit our :ref:`tutorials ` section for examples on using your |CL| system. + +Related topics +************** + +* :ref:`azure` +* :ref:`gce` +* :ref:`clr-digitalocean` diff --git a/source/get-started/cloud-install/azure.rst b/source/get-started/cloud-install/azure.rst index 66c48bf8..a6cc1f20 100644 --- a/source/get-started/cloud-install/azure.rst +++ b/source/get-started/cloud-install/azure.rst @@ -519,6 +519,13 @@ For additional information visit the |CL| To learn more about the MS Azure CLI 2.0 tool and options that are available, visit the `MS Azure documentation and tutorials`_ website. +Related topics +************** + +* :ref:`gce` +* :ref:`aws-web` +* :ref:`clr-digitalocean` + .. _`Azure Portal`: https://portal.azure.com diff --git a/source/get-started/cloud-install/digitalocean.rst b/source/get-started/cloud-install/digitalocean.rst new file mode 100644 index 00000000..94d14c01 --- /dev/null +++ b/source/get-started/cloud-install/digitalocean.rst @@ -0,0 +1,366 @@ +.. _clr-digitalocean: + +|CL-ATTR| on DigitalOcean\* +########################### + +This guide explains how to import a |CL-ATTR| image to `DigitalOcean`_ +and then deploy a VM instance. + +.. contents:: + :local: + :depth: 1 + +Prerequisites +************* + +* Set up a DigitalOcean account. + +* Create an SSH key on your client system that you will use to remote + into the VM. You can follow the `DigitalOcean's SSH key creation guide`_. + +Add |CL| Image to DigitalOcean +****************************** + +Before you can deploy a |CL| instance on DigitalOcean, you need to add +an image since it's currently not available in its marketplace. +You can use our pre-built image or you can build your own custom image. + +Use pre-built image +=================== + +.. note:: + Our cloud images (`clear--digitalocean.img.gz`) for + DigitalOcean are considered **Beta** until we finish setting up our + automated testing of the images against the DigitalOcean environment. + Apart from the initial version, `clear-31870-digitalocean.img.gz`_, we + cannot guarantee that future versions and updates to the initial + version is problems-free. + +.. bktan8 - commented out until the images are fully validated by DevOps + and go live on official Downloads page. + Go to the |CL| `downloads` page and copy the URL for the + **Cloud Guest Legacy** image. See Figure 1. + figure:: ../../_figures/digitalocean/01-digitalocean.png + :scale: 100 % + :alt: Cloud Guest Legacy image + Figure 1: Cloud Guest Legacy image + +#. Copy the URL for `clear-31870-digitalocean.img.gz`_. + +#. Skip to the `Upload image`_ section. + +Build custom image +================== + +For this method, you need a |CL| system to generate an image using +the *clr-installer* tool. + +#. Add the *clr-installer* and *gzip* bundles. + + .. code-block:: bash + + sudo swupd bundle-add clr-installer gzip + +#. Create an image configuration YAML file. + See `Installer YAML Syntax`_ for more information on the clr-installer + configuration YAML syntax. + + .. code-block:: bash + + cat > clear-digitalocean.yaml << EOF + #clear-linux-config + + # switch between aliases if you want to install to an actual block device + # i.e /dev/sda + block-devices: [ + {name: "bdevice", file: "clear-digitalocean.img"} + ] + + targetMedia: + - name: \${bdevice} + size: "800M" + type: disk + children: + - name: \${bdevice}1 + fstype: ext4 + options: -O ^64bit + mountpoint: / + size: "800M" + type: part + + bundles: [ + bootloader, + openssh-server, + os-cloudguest, + os-core, + os-core-update, + systemd-networkd-autostart + ] + + autoUpdate: false + postArchive: false + postReboot: false + telemetry: false + legacyBios: true + + keyboard: us + language: en_US.UTF-8 + kernel: kernel-kvm + + version: 0 + EOF + + The settings that are required in order to make the image + work on DigitalOcean are: + + * *os-cloudguest* bundle: Allows DigitalOcean to provision the + image with settings such as hostname, resource (CPU, memory, + storage) sizing, and user creation. + * *legacyBios: true*: The image need to support legacy BIOS to boot + on DigitalOcean. + +#. Generate the image. + + .. code-block:: bash + + sudo clr-installer -c clear-digitalocean.yaml + + The output should be :file:`clear-digitalocean.img`. + +#. Compress the image with *gzip* to save bandwidth and upload time. + + .. code-block:: bash + + gzip clear-digitalocean.img + + The output should be :file:`clear-digitalocean.img.gz`. + + .. note:: + + *bzip2* is the other compression format DigitalOcean accepts. + +Upload image +============ + +#. On DigitalOcean's website, go to :menuselection:`MANAGE --> Images + --> Custom Images`. + + See Figure 1. + + .. rst-class:: dropshadow + + .. figure:: ../../_figures/digitalocean/01-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Upload custom images + + Figure 1: DigitalOcean - Upload custom images + +#. Select an upload method. + + * To import a pre-built image from |CL| `downloads`_, click + :guilabel:`Import via URL`, paste the URL, and click :guilabel:`Next`. + + See Figure 2. + + .. figure:: ../../_figures/digitalocean/02-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Import via URL + + Figure 2: DigitalOcean - Import via URL + + * To import your custom image, click :guilabel:`Upload Image` + and select the image from your client system. + +#. Set the :guilabel:`DISTRIBUTION` type as :guilabel:`Unknown`. + + See Figure 3. + + | + +#. Choose your preferred datacenter region. + +#. Click :guilabel:`Upload Image`. + Wait for the upload to finish before proceeding to the next section. + + .. figure:: ../../_figures/digitalocean/03-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Set image distribution type, region, tag + + Figure 3: DigitalOcean - Set image distribution type, region, tag + +Create and Deploy a |CL| Instance +********************************* + +#. On DigitalOcean's website, go to :menuselection:`MANAGE --> Droplets` + and then click :guilabel:`Create Droplet`. + + See Figure 4. + + .. figure:: ../../_figures/digitalocean/04-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Create Droplet + + Figure 4: DigitalOcean - Create Droplet + +#. Under :guilabel:`Choose an image`, select :guilabel:`Custom images`. + + See Figure 5. + + | + +#. Select your uploaded |CL| image. + + .. figure:: ../../_figures/digitalocean/05-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Choose custom image + + Figure 5: DigitalOcean - Choose custom image + +#. Under :guilabel:`Choose a plan`, select your preferred plan. + + See Figure 6. + + .. figure:: ../../_figures/digitalocean/06-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Choose plan + + Figure 6: DigitalOcean - Choose plan + +#. Under :guilabel:`Choose a datacenter region`, select the region you + want the instance deployed to. + + See Figure 7. + + .. figure:: ../../_figures/digitalocean/07-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Choose datacenter region + + Figure 7: DigitalOcean - Choose datacenter region + +#. Assign SSH key to default *clear* user. + + By default, the user *clear* will be added to the instance and + an SSH key must be assigned to this account. + + a. Under :guilabel:`Authentication`, select :guilabel:`SSH keys` and + click :guilabel:`New SSH Key`. + + See Figure 8. + + .. figure:: ../../_figures/digitalocean/08-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Add SSH key + + Figure 8: DigitalOcean - Add SSH key + + #. Copy and paste your SSH public key in the :guilabel:`SSH key content` + text field. + + See Figure 9. + + | + + #. Give a name for the SSH key. + + #. Click :guilabel:`Add SSH Key`. + + .. figure:: ../../_figures/digitalocean/09-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Add public SSH key + + Figure 9: DigitalOcean - Add public SSH key + + .. note:: + + If you need to add additional users to the instance, you can do that + wth a YAML-formatted *cloud-config* user data script. + For more information on cloud-config scripting for |CL|, see our + subset implementation of cloud-init called `micro-config-drive`_. + + a. Under :guilabel:`Select additional options`, + select :guilabel:`User data`. + + #. Add your YAML-formatted *cloud-config* user data in the field below. + Here is a simple example: + + .. code-block:: console + + #cloud-config + + users: + - name: foobar + gecos: Foo B. Bar + homedir: /home/foobar + ssh-authorized-keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC65OihS4UP27xKOpqKWgT9 + mgUNwEqhUEpTGGvopjT65Y/KU9Wfj6EYsdGzbHHcMUhFSTxAUAV4POH5d0LR + MzI7sXMe528eCmpm2fTOHDDkVrurP/Jr2bjB9IrfSMkBYS8uRd603xNg/RDq + EH3XzVeEDdEAxoej0mzsJ2UkQSBi+PD1J7JeCbX2lsb55x2yWzaUa+BTai7+ + /TU4UabTRDtFTiXhx2rImSSguofDISVll6W5TTzbGmHdoEI+8DIAFU66ZgC9 + SzL75LQi1YAWlj5XG+dXhN6Ev6KFM34odvWdxeCj0jcx5UIXcieBfOuLujEH + dVybwNLG7hxDy/67BA1j username@mydomain.com + sudo: + - [ "ALL=(ALL) NOPASSWD:ALL" ] + +#. Under :guilabel:`Finalize and create`: + + a. Set the number of instances you want to deploy. + + #. Set the hostname for the instance. + + See Figure 10. + + | + +#. Click :guilabel:`Create Droplet` to deploy the instance. + + .. figure:: ../../_figures/digitalocean/10-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Finalize and create Droplet + + Figure 10: DigitalOcean - Finalize and create Droplet + +Connect to Your |CL| Instance +***************************** + +#. On DigitalOcean's website, go to :menuselection:`MANAGE --> Droplets`. + + See Figure 11. + + | + +#. Get the IP address of your |CL| instance. + + .. figure:: ../../_figures/digitalocean/11-digitalocean.png + :scale: 100 % + :alt: DigitalOcean - Get Droplet IP address + + Figure 11: DigitalOcean - Get Droplet IP address + +#. On your client system, SSH into your instance. + For example: + + .. code-block:: bash + + ssh clear@ -i + + +Related topics +************** + +* :ref:`gce` +* :ref:`azure` +* :ref:`aws-web` + +.. _clear-31870-digitalocean.img.gz: https://cdn.download.clearlinux.org/releases/31870/clear/clear-31870-digitalocean.img.gz + +.. _DigitalOcean: https://www.digitalocean.com/ + +.. _DigitalOcean's SSH key creation guide: https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/create-with-openssh/ + +.. _downloads: https://clearlinux.org/downloads + +.. _Installer YAML Syntax: + https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md + +.. _micro-config-drive: https://github.com/clearlinux/micro-config-drive diff --git a/source/get-started/cloud-install/gce.rst b/source/get-started/cloud-install/gce.rst index 85c583cf..8a684c47 100644 --- a/source/get-started/cloud-install/gce.rst +++ b/source/get-started/cloud-install/gce.rst @@ -260,7 +260,7 @@ Related topics * :ref:`azure` * :ref:`aws-web` - +* :ref:`clr-digitalocean` .. _Google Cloud Platform: https://cloud.google.com/ diff --git a/source/get-started/index.rst b/source/get-started/index.rst index 02f4a15f..bab843b5 100644 --- a/source/get-started/index.rst +++ b/source/get-started/index.rst @@ -35,6 +35,7 @@ Install bare-metal-install-desktop bare-metal-install-server install-configfile + ipxe-install .. _virtual-machine-install: diff --git a/source/get-started/ipxe-install.rst b/source/get-started/ipxe-install.rst new file mode 100644 index 00000000..ae817de6 --- /dev/null +++ b/source/get-started/ipxe-install.rst @@ -0,0 +1,580 @@ +.. _ipxe-install: + +Install |CL| Over the Network with iPXE +####################################### + +PXE :abbr:`PXE (Pre-boot Execution Environment)` is an industry standard +that describes client-server interaction with network-boot software and +uses the DHCP and TFTP protocols. iPXE, a fork of gPXE, is an open-source +version of PXE. It enables computers without built-in PXE capability to +network-boot using protocols such as HTTP, :abbr:`iSCSI (Internet Small +Computer Systems Interface)`, :abbr:`AoE (ATA over Ethernet\*)`, and +:abbr:`FCoE (Fiber Channel over Ethernet\*)`. + +This guide demonstrates how to setup an iPXE server to install |CL-ATTR| +over the network. + +Figure 1 depicts the flow of information between an iPXE server and a +PXE client. + +.. figure:: ../_figures/ipxe/ipxe-install-1.png + :alt: PXE information flow + + Figure 1: PXE information flow + +.. caution:: + + The |CL| PXE image that boots through the iPXE process automatically + erases all data and partitions on the PXE client system and performs + a fresh installation according to a clr-installer YAML configuration + file. + +Prerequisites +************* + +Your iPXE server must have: + +* Ethernet/LAN boot option +* At least two network adapters +* Connection to a public (WAN) network +* Secure Boot option disabled in BIOS + +Your clients must have: + +* Ethernet/LAN boot option +* One network adapter +* Secure Boot option disabled in BIOS +* The minimum requirements to run |CL|. Review the :ref:`compatibility-check`. + +Connect the iPXE server and clients to a network switch on a private +(LAN) network, as shown in Figure 2. + +.. figure:: ../_figures/ipxe/ipxe-install-2.png + :alt: Network topology + + Figure 2: Network topology + +Install |CL| on server +********************** + +#. Install |CL| on the system that will serve as the iPXE server. + We recommend using the `server` version. + +#. Open a terminal window. + +#. Add the :command:`pxe-server` bundle to your |CL| system. + The bundle contains all the necessary apps (web server, iPXE firmwares, + dnsmasq which provides TFTP, DNS, DHCP functionalities) to run an + iPXE server. + + .. code-block:: bash + + sudo swupd bundle-add pxe-server + +#. Define the following variables used for setting up the iPXE server. + Be sure to substitute the value for the WAN_INTERFACE and + LAN_INTERFACE variables with your LAN and WAN interfaces names. + Use :command:`ip a` to list your network devices and get their + names. + + .. code-block:: bash + + IPXE_APP_NAME=ipxe + IPXE_PORT=50000 + WEB_ROOT_DIR=/var/www + IPXE_ROOT_DIR=${WEB_ROOT_DIR}/${IPXE_APP_NAME} + TFTP_ROOT_DIR=/srv/tftp + CLR_INSTALLER_CONF_DIR=clr-installer-configs + WAN_INTERFACE=eno1 + LAN_INTERFACE=eno2 + IPXE_SUBNET=192.168.100 + IPXE_LAN_IP=${IPXE_SUBNET}.1 + IPXE_SUBNET_MASK_IP=255.255.255.0 + IPXE_SUBNET_BITMASK=16 + +Setup nginx web server to host iPXE +*********************************** + +#. Set up an nginx web server to serve the |CL| PXE image to clients + using these steps: + + .. code-block:: bash + + sudo mkdir -p /etc/nginx/conf.d + sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf + sudo tee -a /etc/nginx/conf.d/${IPXE_APP_NAME}.conf << EOF + server { + listen ${IPXE_PORT}; + server_name localhost; + # directory to store ipxe + location /${IPXE_APP_NAME}/ { + root ${WEB_ROOT_DIR}/${IPXE_APP_NAME}; + rewrite ^/${IPXE_APP_NAME}(/.*)$ \$1 break; + } + # directory to store clr-installer configs + location /${CLR_INSTALLER_CONF_DIR}/ { + root ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}; + rewrite ^/${CLR_INSTALLER_CONF_DIR}(/.*)$ \$1 break; + } + } + EOF + +#. Set nginx to start automatically on boot and then start it. + + .. code-block:: bash + + sudo systemctl enable nginx + sudo systemctl start nginx + +Configure iPXE +************** + +#. Download the latest |CL| PXE image and extract the files into the iPXE root. + + .. code-block:: bash + + sudo curl -o /tmp/clear-pxe.tar.xz \ + https://cdn.download.clearlinux.org/current/clear-$(curl \ + https://cdn.download.clearlinux.org/latest)-pxe.tar.xz + sudo mkdir -p ${IPXE_ROOT_DIR} + sudo tar -xJf /tmp/clear-pxe.tar.xz -C ${IPXE_ROOT_DIR} + sudo ln -sf $(ls ${IPXE_ROOT_DIR} | grep 'org.clearlinux.*') ${IPXE_ROOT_DIR}/linux + + .. note:: + + Ensure that the initial ramdisk file is named :file:`initrd` and + the kernel file is named :file:`linux`, which is a symbolic link to the + actual kernel file. + +#. Create an iPXE boot script. The script presents a menu of bootable images to + download, boot, and install |CL|, according to a designated clr-installer + YAML configuration file. + + .. code-block:: bash + + sudo tee -a ${IPXE_ROOT_DIR}/ipxe_boot_script.ipxe << EOF + #!ipxe + + set menu-timeout 5000 + set submenu-timeout \${menu-timeout} + isset \${menu-default} || set menu-default clr-server + + :menu + menu Select a version of Clear Linux OS to install + item clr-desktop Clear Linux OS (Desktop) + item clr-server Clear Linux OS (Server) + item ipxe-shell iPXE Shell + item reboot Reboot + + choose --timeout \${menu-timeout} --default \${menu-default} selected || goto cancel + set menu-timeout 0 + goto \${selected} + + :clr-desktop + echo Booting and installing Clear Linux OS (Desktop)... + kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug \\ + tsc=reliable no_timer_check noreplace-smp rw initrd=initrd \\ + clri.descriptor=http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-desktop.yaml + initrd initrd + boot || goto failed + + :clr-server + echo Booting and installing Clear Linux OS (Server)... + kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug \\ + tsc=reliable no_timer_check noreplace-smp rw initrd=initrd \\ + clri.descriptor=http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-server.yaml + initrd initrd + boot || goto failed + + :cancel + echo Menu canceled, going to iPXE shell + + :ipxe-shell + echo Type 'exit' to return to the menu + shell + set menu-timeout 0 + set submenu-timeout 0 + goto menu + + echo Booting + :failed + echo Booting failed, going to iPXE shell + goto shell + + :reboot + echo Rebooting... + sleep 1 + reboot + EOF + + .. note:: + + The `clri.discriptor` option tells clr-installer where to download a YAML + configuration file to use. Without this option, the |CL| PXE image will + simply boot and not perform any installation. + +Add clr-installer YAML configuration files +****************************************** + +After the |CL| PXE image boot, clr-installer downloads the YAML configuration file +specified in the kernel command-line and installs accordingly. + +See `Installer YAML Syntax`_ for more information on clr-installer configuration +YAML syntax. + +#. Create the directory to store the configuration files. + + .. code-block:: bash + + sudo mkdir -p ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR} + +#. Create this sample `Desktop` configuration called :file:`clr-desktop.yaml`. + + .. code-block:: bash + + sudo tee -a ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}/clr-desktop.yaml << EOF + #clear-linux-config + + # switch between aliases if you want to install to an actuall block device + # i.e /dev/sda + block-devices: [ + {name: "bdevice", file: "/dev/sda"} + ] + + targetMedia: + - name: \${bdevice} + type: disk + children: + - name: \${bdevice}1 + fstype: vfat + mountpoint: /boot + size: "150M" + type: part + - name: \${bdevice}2 + fstype: swap + size: "250M" + type: part + - name: \${bdevice}3 + fstype: ext4 + mountpoint: / + size: "0" # Use remaining disk space + type: part + + bundles: [ bootloader, os-core, os-core-update, desktop-autostart, libreoffice, + vlc, c-basic, git, openssh-server, vim ] + + autoUpdate: true + postArchive: false + postReboot: true + telemetry: false + hostname: clrlinux-desktop + keyboard: us + language: en_US.UTF-8 + kernel: kernel-native + + users: + - login: clrlinux + username: Clear Linux + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + - login: root + username: Root Root + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + + pre-install: [ + {cmd: "curl -o /tmp/add-issue.sh http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh"}, + {cmd: "chmod +x /tmp/add-issue.sh"} + ] + + post-install: [ + {cmd: "echo PermitRootLogin yes > \${chrootDir}/etc/ssh/sshd_config"}, + {cmd: "/tmp/add-issue.sh \${chrootDir}"} + ] + EOF + + +#. Create this sample `Server` configuration called :file:`clr-server.yaml`. + + .. code-block:: bash + + sudo tee -a ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}/clr-server.yaml << EOF + #clear-linux-config + + # switch between aliases if you want to install to an actuall block device + # i.e /dev/sda + block-devices: [ + {name: "bdevice", file: "/dev/sda"} + ] + + targetMedia: + - name: \${bdevice} + type: disk + children: + - name: \${bdevice}1 + fstype: vfat + mountpoint: /boot + size: "150M" + type: part + - name: \${bdevice}2 + fstype: swap + size: "250M" + type: part + - name: \${bdevice}3 + fstype: ext4 + mountpoint: / + size: "0" # Use remaining disk space + type: part + + bundles: [ bootloader, os-core, os-core-update, vim ] + + autoUpdate: true + postArchive: false + postReboot: true + telemetry: false + hostname: clrlinux-server + keyboard: us + language: en_US.UTF-8 + kernel: kernel-native + + users: + - login: clrlinux + username: Clear Linux + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + - login: root + username: Root Root + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + + pre-install: [ + {cmd: "curl -o /tmp/add-issue.sh http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh"}, + {cmd: "chmod +x /tmp/add-issue.sh"} + ] + + post-install: [ + {cmd: "echo PermitRootLogin yes > \${chrootDir}/etc/ssh/sshd_config"}, + {cmd: "/tmp/add-issue.sh \${chrootDir}"} + ] + EOF + +#. Add following content to the :file:`add-issue.sh` script, which will be + used by the above two YAML configuration files: + + .. code-block:: bash + + sudo tee -a ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh << EOF + #!/bin/bash + echo "Creating custom issue file for \$1" + + echo "Welcome to the Clear Linux* OS + + * Documentation: https://clearlinux.org/documentation + * Community Support: https://community.clearlinux.org + + " >> \$1/etc/issue + + exit 0 + EOF + +Configure network +***************** + +#. The DNS server, included with the `pxe-server` bundle, + conflicts with the DNS stub listener provided in `systemd-resolved`. + Disable the DNS stub listener and temporarily stop `systemd-resolved`. + + .. code-block:: bash + + sudo mkdir -p /etc/systemd + sudo tee -a /etc/systemd/resolved.conf << EOF + [Resolve] + DNSStubListener=no + EOF + + sudo systemctl stop systemd-resolved + +#. Disable NetworkManager. The base installation of |CL| comes with two + network managers, systemd-networkd and NetworkManager, with the latter + being the default. systemd-networkd is recommended for a server use case, + so we will disable NetworkManager. + + .. code-block:: bash + + sudo systemctl mask --now NetworkManager + +#. Assign a static IP address to the LAN side network adapter + and restart `systemd-networkd`. + + .. code-block:: bash + + sudo mkdir -p /etc/systemd/network + sudo tee -a /etc/systemd/network/70-internal-static.network << EOF + [Match] + Name=${LAN_INTERFACE} + [Network] + DHCP=no + Address=${IPXE_LAN_IP}/${IPXE_SUBNET_BITMASK} + EOF + + sudo systemctl enable systemd-networkd + sudo systemctl restart systemd-networkd + +Setup NAT +********* + +#. Configure :abbr:`NAT (Network Address Translation)` to route traffic from + the LAN to the WAN network so clients can download upstream bundles for + installation. And to make these changes persistent during reboots, save the + changes to the firewall. + + .. code-block:: bash + + sudo iptables -t nat -F POSTROUTING + sudo iptables -t nat -A POSTROUTING -o ${WAN_INTERFACE} -j MASQUERADE + sudo systemctl enable iptables-save.service + sudo systemctl restart iptables-save.service + sudo systemctl enable iptables-restore.service + sudo systemctl restart iptables-restore.service + +#. Configure the kernel to forward network packets to different interfaces. + Otherwise, NAT will not work. + + .. code-block:: bash + + sudo mkdir -p /etc/sysctl.d + sudo tee -a /etc/sysctl.d/80-nat-forwarding.conf << EOF + net.ipv4.ip_forward=1 + EOF + + sudo tee -a /proc/sys/net/ipv4/ip_forward << EOF + 1 + EOF + +Setup dnsmaq for DHCP, DNS, and TFTP functionalities +**************************************************** + +#. Create a configuration file for `dnsmasq` to listen on a dedicated IP address + for TFTP, DNS, and DHCP functions. PXE clients on the LAN network will talk to + this IP address. + + .. code-block:: bash + + sudo tee -a /etc/dnsmasq.conf << EOF + listen-address=${IPXE_LAN_IP} + EOF + +#. Add the options to serve iPXE firmware images to clients over TFTP to + the :file:`dnsmasq` configuration file. + + .. code-block:: bash + + sudo tee -a /etc/dnsmasq.conf << EOF + enable-tftp + tftp-root=${TFTP_ROOT_DIR} + EOF + +#. Add the options to host a DHCP server for clients to the :file:`dnsmasq` + configuration file. + + .. code-block:: bash + + sudo tee -a /etc/dnsmasq.conf << EOF + dhcp-leasefile=/var/db/dnsmasq.leases + + dhcp-authoritative + dhcp-option=option:router,${IPXE_LAN_IP} + dhcp-option=option:dns-server,${IPXE_LAN_IP} + + dhcp-match=set:ipxeclient,60,IPXEClient* + dhcp-range=tag:ipxeclient,${IPXE_SUBNET}.2,${IPXE_SUBNET}.253,${IPXE_SUBNET_MASK_IP},15m + dhcp-range=tag:!ipxeclient,${IPXE_SUBNET}.2,${IPXE_SUBNET}.253,${IPXE_SUBNET_MASK_IP},6h + + dhcp-match=set:ipxeboot,175 + dhcp-boot=tag:ipxeboot,http://${IPXE_LAN_IP}:${IPXE_PORT}/${IPXE_APP_NAME}/ipxe_boot_script.ipxe + dhcp-boot=tag:!ipxeboot,undionly.kpxe,${IPXE_LAN_IP} + EOF + + The configuration provides the following important functions: + + * Directs clients without an iPXE implementation to the TFTP server + to acquire architecture-specific iPXE firmware images that allow them + to perform an iPXE boot. + * Activates only on the network adapter that has an IP address on the + defined subnet. + * Directs clients to the DNS server. + * Directs clients to the iPXE server for routing via NAT. + * Divides the private network into two pools of IP addresses. One pool + is for network boot and one pool is used after boot. Each pool has + their own lease times. + +#. Create a file for `dnsmasq` to record the IP addresses it provides + to clients. + + .. code-block:: bash + + sudo mkdir -p /var/db + sudo touch /var/db/dnsmasq.leases + +#. Create a TFTP hosting directory and populate it with the iPXE firmware. + + .. code-block:: bash + + sudo mkdir -p ${TFTP_ROOT_DIR} + sudo ln -sf /usr/share/ipxe/undionly.kpxe ${TFTP_ROOT_DIR}/undionly.kpxe + +#. Start `dnsmasq` and enable startup on boot. + + .. code-block:: bash + + sudo systemctl daemon-reload + sudo systemctl enable dnsmasq + sudo systemctl restart dnsmasq + +#. Start `systemd-resolved`. + + .. code-block:: bash + + sudo systemctl start systemd-resolved + + .. note:: + + `systemd-resolved` dynamically updates the list of DNS servers for the + LAN network if you use the `dnsmasq` DNS server. The setup creates a + pass-through DNS server that relies on the DNS servers listed in + :file:`/etc/resolv.conf`. + +Verify setup +************ + +Verify you can access these URLs before deploying: + +* \http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${IPXE_APP_NAME}/ipxe_boot_script.ipxe +* \http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-desktop.yaml +* \http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-server.yaml +* \http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh + +Deploy +****** + +#. Connect your client system to the LAN network. + +#. Power on the client. + +#. Set your client to network boot. It should get an IP address and download + the iPXE script. + +#. When presented with the iPXE menu, select one of the options. The client + will then download and boot the |CL| image. Once booted, clr-installer will + download the assigned YAML configuration file and begin to install |CL|. + After installation, the client will reboot to |CL|. + +.. _iPXE: + http://ipxe.org/ + +.. _Installer YAML Syntax: + https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-15.png b/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-15.png deleted file mode 100644 index 7d2111fa..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-15.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png deleted file mode 100644 index 89ad86e6..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/hyper-v.rst b/source/get-started/virtual-machine-install/hyper-v.rst index 35038c57..dab56ada 100644 --- a/source/get-started/virtual-machine-install/hyper-v.rst +++ b/source/get-started/virtual-machine-install/hyper-v.rst @@ -61,7 +61,7 @@ Create and configure new VM :scale: 100% :alt: Hyper-V Manager from the Start menu - Figure 1: Hyper-V Manager from the Start menu + Figure 1: Hyper-V Manager from the Start menu #. Create a *New Virtual Machine* by clicking the :guilabel:`Action` menu, @@ -71,7 +71,7 @@ Create and configure new VM :scale: 100% :alt: New Virtual Machine in Hyper-V Manager - Figure 2: New Virtual Machine in Hyper-V Manager + Figure 2: New Virtual Machine in Hyper-V Manager #. Follow the *New Virtual Machine Wizard* to create a new virtual machine specifying the options below: @@ -102,7 +102,7 @@ Create and configure new VM :scale: 100% :alt: |CL| VM Settings in Hyper-V Manager - Figure 3: |CL| VM Settings page after configuration + Figure 3: |CL| VM Settings page after configuration #. Click :guilabel:`Apply` at the bottom of the VM Settings screen. diff --git a/source/get-started/virtual-machine-install/parallels.rst b/source/get-started/virtual-machine-install/parallels.rst index 53c26295..eeaf8f67 100644 --- a/source/get-started/virtual-machine-install/parallels.rst +++ b/source/get-started/virtual-machine-install/parallels.rst @@ -3,8 +3,7 @@ |CL-ATTR| on Parallels\* Desktop 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. +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\*. @@ -28,7 +27,7 @@ Download ISO image .. code-block:: bash - gunzip clear-30140-live-server.iso.xz + gunzip clear-30140-live-server.iso.xz Initialize new VM ***************** @@ -43,43 +42,43 @@ following steps. :guilabel:`Continue`. (See Figure 1.) .. figure:: /_figures/parallels/parallels-01.png - :alt: Parallels opening dialog + :alt: Parallels opening dialog - Figure 1: Parallels opening dialog + Figure 1: Parallels opening dialog #. On the next screen, select :guilabel:`Image File`, then click :guilabel:`Select a file...` as shown in Figure 2. .. figure:: /_figures/parallels/parallels-02.png - :alt: Dialog to select source for VM + :alt: Dialog to select source for VM - Figure 2: Dialog to select source for VM + Figure 2: Dialog to select source for VM #. Select your ISO file. The system displays the warning message "Unable to detect operating system", as shown in Figure 3. This message is expected and can be ignored. Click :guilabel:`Continue`. .. figure:: /_figures/parallels/parallels-03.png - :alt: Warning that OS is not detected + :alt: Warning that OS is not detected - Figure 3: Warning that OS is not detected + Figure 3: Warning that OS is not detected #. You are prompted to select your OS, as shown in Figure 4. Select :menuselection:`More Linux > Other Linux` from the drop-down menu and click :guilabel:`Continue`. .. figure:: /_figures/parallels/parallels-04.png - :alt: Select OS from drop-down menu + :alt: Select OS from drop-down menu - Figure 4: Select OS from drop-down menu + Figure 4: Select OS from drop-down menu #. Name your VM and check :guilabel:`Customize settings before installation`. (See Figure 5.) .. figure:: /_figures/parallels/parallels-05.png - :alt: Name and Location screen + :alt: Name and Location screen - Figure 5: Name and Location screen + Figure 5: Name and Location screen #. Click :guilabel:`Create`. The Configuration window for the new VM opens, as shown in Figure 6. @@ -87,18 +86,18 @@ following steps. Select :menuselection:`Hardware > Boot Order`. .. figure:: /_figures/parallels/parallels-06.png - :alt: VM Configuration window + :alt: VM Configuration window - Figure 6: VM Configuration window + Figure 6: VM Configuration window #. Expand :guilabel:`Advanced Settings`. Set :guilabel:`BIOS` to “EFI 64-bit” and in the :guilabel:`Boot flags` field, enter “vm.bios.efi=1” as shown in Figure 7. .. figure:: /_figures/parallels/parallels-07.png - :alt: Advanced configuration settings + :alt: Advanced configuration settings - Figure 7: Advanced configuration settings + Figure 7: Advanced configuration settings #. Close the Configuration window and click :guilabel:`Continue`. @@ -115,18 +114,18 @@ Install |CL| on VM instructions. .. figure:: /_figures/parallels/parallels-08.png - :alt: On screen instructions from text-based installer + :alt: On screen instructions from text-based installer - Figure 8: On screen instructions from text-based installer + Figure 8: On screen instructions from text-based installer #. After installation, reboot the VM. You are prompted to log in, as shown in Figure 9. Log in with the credentials you used when you installed |CL| on the VM. .. figure:: /_figures/parallels/parallels-09.png - :alt: Log in prompt + :alt: Log in prompt - Figure 9: Log in prompt + Figure 9: Log in prompt Congratulations! You have successfully set up a |CL| VM using Parallels diff --git a/source/get-started/virtual-machine-install/vmw-player-preconf.rst b/source/get-started/virtual-machine-install/vmw-player-preconf.rst deleted file mode 100644 index 8420e7df..00000000 --- a/source/get-started/virtual-machine-install/vmw-player-preconf.rst +++ /dev/null @@ -1,308 +0,0 @@ -.. _vmw-player-preconf: - -|CL-ATTR| on VMware\* Workstation Player (pre-configured image) -############################################################### - -This page explains how to deploy a pre-configured |CL| VMware image on -`VMware Workstation 14 Player`_. - -.. contents:: - :local: - :depth: 1 - -Overview -******** - -VMware Workstation 14 Player is a type 2 hypervisor. For example, it runs on -top of Windows\* or Linux\* operating system. With VMware ESXi, you -can create, configure, manage, and run |CL-ATTR| -:abbr:`VMs (Virtual Machines)` on your local system. - -.. note:: - - Screenshots in this document show VMware Workstation 14 Player for - Windows. Menus and prompts in the Linux version have minor wording - differences. - -Install the VMware Workstation Player hypervisor -************************************************ - -#. Enable :abbr:`Intel® VT (Intel® Virtualization Technology)` and - :abbr:`Intel® VT-d (Intel® Virtualization Technology for Directed I/O)` in - your system's BIOS. - -#. `VMware Workstation 14 Player`_ is available for Windows and Linux. - Download your preferred version. - -#. Depending on which OS you're running, install it by following one of these - instructions: - - * On supported Linux distros: - - #. Enable a GUI desktop. - - #. Start a terminal emulator. - - #. Start the installer by issuing the command below and following the - guided steps. - - .. code-block:: bash - - sudo sh ./VMware-Player-[version number].x86_64.bundle - - * On Windows: - - #. Start the installer. - #. Follow the setup wizard. - -For additional help, see the `VMware Workstation Player Documentation`_. - -Download the latest |CL| VMware image -************************************* - -Get the latest |CL| VMware image from the `image repository`_. -Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use -this command: - -.. code-block:: bash - - curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep vmware) - -Decompress and verify the image -******************************* - -Visit :ref:`download-verify-decompress` and follow the instructions for your -Windows\* or Linux\* environment. Visit :ref:`image-types` for additional -information about all available |CL| images. - -Create and configure a new VM -***************************** - -#. Start the `VMware Workstation Player` app. -#. On the home screen, click :guilabel:`Create a New Virtual Machine`. See - figure 1. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-01.png - :scale: 100% - :alt: VMware Workstation 14 Player - Create a new virtual machine - - Figure 1: VMware Workstation 14 Player - Create a new virtual machine - -#. On the :guilabel:`Welcome to the New Virtual Machine Wizard` screen, - select the :guilabel:`I will install the operating system later` option. - See figure 2. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-02.png - :scale: 100% - :alt: VMware Workstation 14 Player - Select install operating system - - Figure 2: VMware Workstation 14 Player - Select install operating - system later. - -#. Click the :guilabel:`Next` button. - -#. On the :guilabel:`Select a Guest Operating System` screen, set the - :guilabel:`Guest operating system` setting to :guilabel:`Linux`. - See figure 3. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-03.png - :scale: 100% - :alt: VMware Workstation 14 Player - Select guest operating system type - - Figure 3: VMware Workstation 14 Player - Select guest operating system - type - -#. Set :guilabel:`Version` setting to - :guilabel:`Other Linux 3.x or later kernel 64-bit`. - -#. Click the :guilabel:`Next` button. - -#. On the :guilabel:`Name the Virtual Machine` screen, give your new VM a - name. See figure 4. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-04.png - :scale: 100% - :alt: VMware Workstation 14 Player - Name virtual machine - - Figure 4: VMware Workstation 14 Player - Name virtual machine - -#. Click the :guilabel:`Next` button. - -#. On the :guilabel:`Specify Disk Capacity` screen, click - the :guilabel:`Next` button. Keep the default disk settings unchanged. - When we attach the pre-configured |CL| VMware image, we will remove the - default virtual disk and replace it with the pre-configured one. See - figure 5. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-05.png - :scale: 100% - :alt: VMware Workstation 14 Player - Set disk capacity - - Figure 5: VMware Workstation 14 Player - Set disk capacity - -#. On the :guilabel:`Ready to Create Virtual Machine` screen, click the - :guilabel:`Customize Hardware...` button. See figure 6. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-06.png - :scale: 100% - :alt: VMware Workstation 14 Player - Customize hardware - - Figure 6: VMware Workstation 14 Player - Customize hardware - -#. Under the :guilabel:`Device` list, select :guilabel:`Processors`. See - figure 7. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-07.png - :scale: 100% - :alt: VMware Workstation 14 Player - Set virtualization engine option - - Figure 7: VMware Workstation 14 Player - Set virtualization engine - option - -#. Under the :guilabel:`Virtualization engine` section, - check :guilabel:`Virtualize Intel VT-x/EPT or AMD-V/RVI`. - -#. To disconnect the virtual CD/DVD (IDE) since it is not needed, under the - :guilabel:`Device` list, select :guilabel:`New CD/DVD (IDE)`. See figure 8. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-08.png - :scale: 100% - :alt: VMware Workstation 14 Player - Disconnect CD/DVD (IDE) - - Figure 8: VMware Workstation 14 Player - Disconnect CD/DVD (IDE) - -#. Under the :guilabel:`Device status` section, uncheck - :guilabel:`Connect at power on`. - -#. Click the :guilabel:`Close` button. - -#. Click the :guilabel:`Finish` button. - -Attach the pre-configured |CL| VMware image -******************************************* - -#. Move the downloaded and decompressed pre-configured |CL| VMware image file - :file:`clear-[version number]-basic.vmdk` to the directory where your - newly-created VM resides. - - .. note:: - - Depending on the OS, you can typically find the VMware VM files under: - - * On Linux distros: :file:`/home/username/vmware` - * On Windows: :file:`C:\Users\username\Documents\Virtual Machines` - -#. On the :guilabel:`VMware Workstation Player` home screen, select your - newly-created VM. See figure 9. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-09.png - :scale: 100% - :alt: VMware Workstation 14 Player - Edit virtual machine settings - - Figure 9: VMware Workstation 14 Player - Edit virtual machine settings - -#. Click :guilabel:`Edit virtual machine settings`. - -#. To remove the default hard disk, under the :guilabel:`Device` list, select - :guilabel:`Hard Disk (SCSI)`. See figure 10. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-10.png - :scale: 100% - :alt: VMware Workstation 14 Player - Remove hard drive - - Figure 10: VMware Workstation 14 Player - Remove hard drive - -#. Click the :guilabel:`Remove` button. - -#. To add a new hard disk and attach the pre-configured |CL| VMware image, - click the :guilabel:`Add...` button. See Figure 11. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-11.png - :scale: 100% - :alt: VMware Workstation 14 Player - Add new hard drive - - Figure 11: VMware Workstation 14 Player - Add new hard drive - -#. Under the :guilabel:`Hardware types` section, select :guilabel:`Hard Disk`. - -#. Click the :guilabel:`Next` button. - -#. Select your preferred :guilabel:`Virtual disk type`. See figure 12. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-12.png - :scale: 100% - :alt: VMware Workstation 14 Player - Select virtual disk type - - Figure 12: VMware Workstation 14 Player - Select virtual disk type - -#. Select the :guilabel:`Use an existing virtual disk` option. See figure 13. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-13.png - :scale: 100% - :alt: VMware Workstation 14 Player - Use existing virtual disk - - Figure 13: VMware Workstation 14 Player - Use existing virtual disk - -#. Click the :guilabel:`Browse` button and select the pre-configured |CL| - VMware image file. See figure 14. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-14.png - :scale: 100% - :alt: VMware Workstation 14 Player - Select ready-made VMware |CL| - - Figure 14: VMware Workstation 14 Player - Select ready-made VMware |CL| - image file - -#. Click the :guilabel:`Finish` button. - - .. note:: - - When asked to convert the existing virtual disk to a newer format, - selecting either option works. - -Enable UEFI boot support -************************ - -|CL| needs UEFI support to boot. To enable it, add the -following line to the end of your VM's :file:`.vmx` file: - -.. code-block:: console - - firmware = "efi" - -.. note:: - - Depending on the OS, you can typically find the VMware VM files under: - - * On Linux distros: :file:`/home/username/vmware` - * On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines` - -Power on the VM -*************** - -After configuring the settings above, power on your |CL| virtual machine. - -#. On the :guilabel:`VMware Workstation Player` home screen, select your - VM. See figure 15. - - .. figure:: figures/vmw-player-preconf/vmw-player-preconf-15.png - :scale: 100% - :alt: VMware Workstation 14 Player - Power on virtual machine - - Figure 15: VMware Workstation 14 Player - Power on virtual machine - -#. Click :guilabel:`Play virtual machine`. - -Related topics -************** - -For other guides on using the VMWare Player and ESXi, see: - -* :ref:`vmw-player` -* :ref:`vmware-esxi-install-cl` -* :ref:`vmware-esxi-preconfigured-cl-image` - -.. _image repository: https://cdn.download.clearlinux.org/image/ -.. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html -.. _VMware Workstation 14 Player: https://www.vmware.com/products/workstation-player.html -.. _VMware Workstation Player Documentation: https://docs.vmware.com/en/VMware-Workstation-Player/index.html diff --git a/source/get-started/virtual-machine-install/vmw-player.rst b/source/get-started/virtual-machine-install/vmw-player.rst index c32ba83c..9cb76883 100644 --- a/source/get-started/virtual-machine-install/vmw-player.rst +++ b/source/get-started/virtual-machine-install/vmw-player.rst @@ -3,8 +3,7 @@ |CL-ATTR| on VMware\* Workstation Player ######################################## -This page explains how to create a new VM and install |CL| on it with the -VMware Workstation Player hypervisor. +This page explains how to create a new VMware Workstation Player hypervisor and use one of two images: the |CL| Desktop installer iso, or the |CL| Pre-configured VMWare image. .. contents:: :local: @@ -14,9 +13,9 @@ Overview ******** `VMware Workstation Player`_ is a type 2 hypervisor. It runs on top of -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. +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. VMware offers a type 1 hypervisor called `VMware ESXi`_ designed for the cloud environment. For information on how to install |CL| as guest OS on @@ -26,10 +25,8 @@ it, see :ref:`vmware-esxi-install-cl`. The screenshots on this document show the Windows version of the VMware Workstation 15 Player. The menus and prompts are similar to those - in other versions and for the Linux OS save some minor wording differences. - -If you prefer to use a pre-configured |CL| VMware image instead, -see our :ref:`vmw-player-preconf` guide. + in other versions and for the Linux OS save some minor wording + differences. Install the VMware Workstation Player hypervisor ************************************************ @@ -46,8 +43,8 @@ Install the VMware Workstation Player hypervisor By default, selecting download means you receive the latest version of this application. Commands may differ based on the version. -#. Install VMware Workstation Player following the instructions - appropriate for your system's OS: +#. Install VMware Workstation Player by following the instructions + appropriate for your system OS: * On supported Linux distros: @@ -67,43 +64,28 @@ Install the VMware Workstation Player hypervisor For additional help, see the `VMware Workstation Player Documentation`_. -Download the latest |CL| installer -********************************** - -Get the latest installer with |CL| OS Desktop from the `downloads`_ page. - -Visit :ref:`image-types` for additional information about all available |CL| images. - -We also provide instructions for downloading and verifying a Clear Linux ISO. -For more information, refer to :ref:`download-verify-decompress`. - Create and configure a new VM ***************************** -#. Start the `VMware Workstation Player` app. +#. Start the ``VMware Workstation Player`` app. #. On the home screen, click :guilabel:`Create a New Virtual Machine`. See Figure 1. - .. figure:: figures/vmw-player/vmw-player-01.png + .. figure:: /_figures/vmw-player/vmw-player-01.png :scale: 100% :alt: VMware Workstation Player - Create a new virtual machine Figure 1: VMware Workstation Player - Create a new virtual machine -#. On the :guilabel:`Welcome to the New Virtual Machine Wizard` screen, - select the :guilabel:`Installer disc image file (iso)` option. - See Figure 2. +#. Select :guilabel:`I will install the operating system later`. - .. figure:: figures/vmw-player/vmw-player-02.png + .. figure:: /_figures/vmw-player/vmw-player-02.png :scale: 100% - :alt: VMware Workstation Player - Select |CL| installer ISO + :alt: I will install the operating system later. - Figure 2: VMware Workstation Player - Select |CL| installer ISO - -#. Click the :guilabel:`Browse` button and select the decompressed |CL| - installer ISO. + Figure 2: I will install the operating system later. #. Click the :guilabel:`Next` button. @@ -111,7 +93,7 @@ Create and configure a new VM :guilabel:`Guest operating system` setting to :guilabel:`Linux`. See Figure 3. - .. figure:: figures/vmw-player/vmw-player-03.png + .. figure:: /_figures/vmw-player/vmw-player-03.png :scale: 100% :alt: VMware Workstation Player - Select guest operating system type @@ -119,14 +101,14 @@ Create and configure a new VM type #. Set the :guilabel:`Version` setting to - :guilabel:`Other Linux 4.x or later kernel 64-bit`. + :guilabel:`Other Linux 5.x or later kernel 64-bit`. #. Click the :guilabel:`Next` button. #. On the :guilabel:`Name the Virtual Machine` screen, name the new VM. See Figure 4. - .. figure:: figures/vmw-player/vmw-player-04.png + .. figure:: /_figures/vmw-player/vmw-player-04.png :scale: 100% :alt: VMware Workstation Player - Name virtual machine @@ -137,7 +119,7 @@ Create and configure a new VM #. On the :guilabel:`Specify Disk Capacity` screen, set the VM's maximum disk size. See Figure 5. - .. figure:: figures/vmw-player/vmw-player-05.png + .. figure:: /_figures/vmw-player/vmw-player-05.png :scale: 100% :alt: VMware Workstation Player - Set disk capacity @@ -153,7 +135,7 @@ Create and configure a new VM #. On the :guilabel:`Ready to Create Virtual Machine` screen, click the :guilabel:`Customize Hardware...` button. See Figure 6. - .. figure:: figures/vmw-player/vmw-player-06.png + .. figure:: /_figures/vmw-player/vmw-player-06.png :scale: 100% :alt: VMware Workstation Player - Customize hardware @@ -161,13 +143,14 @@ Create and configure a new VM #. Select :guilabel:`Memory` and set the size to 2GB. See Figure 7. - .. figure:: figures/vmw-player/vmw-player-07.png + .. figure:: /_figures/vmw-player/vmw-player-07.png :scale: 100% :alt: VMware Workstation Player - Set memory size Figure 7: VMware Workstation Player - Set memory size .. note:: + The |CL| installer ISO needs a minimum of 2GB of RAM. After completing installation, |CL| can run on as little as 128MB of RAM. Thus, you can reduce the memory size if needed. @@ -176,13 +159,16 @@ Create and configure a new VM #. Under the :guilabel:`Device` list, select :guilabel:`Processors`. See Figure 8. - .. figure:: figures/vmw-player/vmw-player-08.png + .. figure:: /_figures/vmw-player/vmw-player-08.png :scale: 100% :alt: VMware Workstation Player - Set virtualization engine option Figure 8: VMware Workstation Player - Set virtualization engine option +#. Under :guilabel:`Processors` and :guilabel:`Number of processor cores`, + enter 4. + #. Under the :guilabel:`Virtualization engine` section, check :guilabel:`Virtualize Intel VT-x/EPT or AMD-V/RVI`. @@ -197,7 +183,7 @@ Enable UEFI boot support #. Power off the VM. click the :guilabel:`Player` menu. See Figure 9. - .. figure:: figures/vmw-player/vmw-player-09.png + .. figure:: /_figures/vmw-player/vmw-player-09.png :scale: 100% :alt: VMware Workstation Player - Power off virtual machine @@ -205,7 +191,7 @@ Enable UEFI boot support #. Go to :guilabel:`Power` and select :guilabel:`Shut Down Guest`. -#. Add the following line to the end of your VM's :file:`.vmx` file: +#. Add the following line to the end of your VM's :file:`.vmx` file. .. code-block:: console @@ -218,43 +204,164 @@ Enable UEFI boot support * On Linux distros: :file:`/home/username/vmware` * On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines` +Download the latest |CL| image +****************************** + +Download the appropriate image per the tab below. We also provide +additional information about :ref:`image-types` and instructions on how to +:ref:`download-verify-decompress`. + +Attach the appropriate image +============================ + + .. tabs:: + + .. tab:: |CL| Desktop + + This option provides a live-desktop iso installer. + + #. Navigate to the `downloads`_ page and download the |CL| Desktop. + After the download is complete, you will attach this image. + + #. On the :guilabel:`VMware Workstation 15 Player`, right-click the + new VM, created in `Create and configure a new VM`_. + + #. From the pop-up menu, select :guilabel:`Settings`. + + #. From :guilabel:`Virtual Machine settings`, + under :guilabel:`Hardware`, select ``CD/DVD``. + + #. Under :guilabel:`Connection` at right, select + :guilabel:`Use ISO image file`. + + #. Click :guilabel:`Browse` and select the decompressed + |CL| installer ISO. See Figure 10. + + .. figure:: /_figures/vmw-player/vmw-player-10.png + :scale: 100% + :alt: VMware Workstation Player - Select |CL| installer ISO + + Figure 10: VMware Workstation Player - Select |CL| installer + ISO + + #. Follow the guide :ref:`install-on-target-start` to complete the + installation of |CL|. + + #. After the installation completes, reboot the VM. This reboot + restarts the |CL| installer. + + #. To enable the mouse pointer so you access VMware Workstation + Player's menus, press :kbd:`` + :kbd:`` on the keyboard. + + #. To disconnect the CD/DVD to stop it from booting the |CL| + installer ISO again, click the :guilabel:`Player` menu. See + Figure below. + + .. figure:: /_figures/vmw-player/vmw-player-11.png + :scale: 100% + :alt: VMware Workstation Player - Edit CD/DVD settings + + Figure 11: VMware Workstation Player - Edit CD/DVD settings + + #. Go to :menuselection:`Removable Devices-->CD/DVD + (IDE)-->Disconnect`. + + #. Click the :guilabel:`OK` button. + + #. Continue below. + + .. tab:: |CL| Pre-configured VMWare image + + #. Navigate to the `downloads`_ page and select the ``VMware`` + image. Look for :file:`clear-[version number]-vmware.vmdk.xz`. + + #. Move the downloaded and decompressed pre-configured |CL| VMware + image file :file:`clear-[version number]-basic.vmdk` to the + directory where your newly-created VM resides. + + .. note:: + + Depending on the OS, you can typically find the VMware VM + files under: + + * Linux distros :file:`/home/username/vmware` + * Windows :file:`C:\Users\username\Documents\Virtual Machines` + + #. On the :guilabel:`VMware Workstation 15 Player`, right-click the + new VM, created in `Create and configure a new VM`_. + + #. From the pop-up menu, select :guilabel:`Settings`. + + #. Under :guilabel:`Hardware` and :guilabel:`Device` list, select + :guilabel:`Hard Disk (SCSI)`. See figure 12. + + .. figure:: /_figures/vmw-player/vmw-player-preconf-12.png + :scale: 100% + :alt: VMware Workstation Player - Remove hard drive + + Figure 12: VMware Workstation Player - Remove hard drive + + #. Click the :guilabel:`Remove` button. + + #. To add a new hard disk and attach the pre-configured |CL| + VMware image, click the :guilabel:`Add` button. See Figure 13. + + .. figure:: /_figures/vmw-player/vmw-player-preconf-13.png + :scale: 100% + :alt: VMware Workstation Player - Add new hard drive + + Figure 13: VMware Workstation Player - Add new hard drive + + #. Under the :guilabel:`Hardware types` section, select + :guilabel:`Hard Disk`. + + #. Click the :guilabel:`Next` button. + + #. Select your preferred :guilabel:`Virtual disk type`. + See figure 14. + + .. figure:: /_figures/vmw-player/vmw-player-preconf-14.png + :scale: 100% + :alt: VMware Workstation Player - Select virtual disk type + + Figure 14: VMware Workstation Player - Select virtual disk type + + #. Select the :guilabel:`Use an existing virtual disk` option. + See figure 15. + + .. figure:: /_figures/vmw-player/vmw-player-preconf-15.png + :scale: 100% + :alt: VMware Workstation Player - Use existing virtual disk + + Figure 15: VMware Workstation Player - Use existing virtual disk + + #. Click the :guilabel:`Browse` button and select the + pre-configured |CL| VMware image file. See figure 16. + + .. figure:: ../../_figures/vmw-player/vmw-player-preconf-16.png + :scale: 100% + :alt: VMware Workstation Player - Select ready-made VMware |CL| + + Figure 16: VMware Workstation Player - Select ready-made VMware |CL| image file + + #. Click the :guilabel:`Finish` button. + + .. note:: + + When asked to convert the existing virtual disk to a newer format, selecting either option works. + Install |CL| into the new VM **************************** #. Select the newly-created VM and click the :guilabel:`Play virtual machine` - button. See Figure 10. + button. See Figure below. - .. figure:: figures/vmw-player/vmw-player-10.png + .. figure:: /_figures/vmw-player/vmw-player-17.png :scale: 100% :alt: VMware Workstation Player - Power on virtual machine - Figure 10: VMware Workstation Player - Power on virtual machine - -#. Follow the :ref:`install-on-target-start` guide to complete the - installation of |CL|. - -#. After the installation completes, reboot the VM. This reboot restarts the - |CL| installer. - -Detach the |CL| installer ISO from the VM -***************************************** - -#. To enable the mouse pointer so you access VMware Workstation Player's - menus, press :kbd:`` + :kbd:`` on the keyboard. - -#. To disconnect the CD/DVD to stop it from booting the |CL| installer ISO - again, click the :guilabel:`Player` menu. See Figure 11. - - .. figure:: figures/vmw-player/vmw-player-11.png - :scale: 100% - :alt: VMware Workstation Player - Edit CD/DVD settings - - Figure 11: VMware Workstation Player - Edit CD/DVD settings - -#. Go to :menuselection:`Removable Devices-->CD/DVD (IDE)-->Disconnect`. - -#. Click the :guilabel:`OK` button. - + Figure 17: VMware Workstation Player - Power on virtual machine + Install open-vm-tools ********************* @@ -262,8 +369,9 @@ Optional: You may want to install the `open-vm-tools` in your virtual machine. The Open Virtual Machine Tools (open-vm-tools) are the open source implementation of VMware Tools for Linux\* guest operating systems. -#. Power on your |CL| virtual machine. On the - :guilabel:`VMware Workstation Player` home screen, select your VM. See Figure 10. +#. Power on your |CL| virtual machine. On the +:guilabel:`VMware Workstation Player` home screen, select your VM. +See Figure 10. #. Click :guilabel:`Play virtual machine`. @@ -282,9 +390,7 @@ Related topics For other guides on using the VMWare Player and ESXi, see: -* :ref:`vmw-player-preconf` * :ref:`vmware-esxi-install-cl` -* :ref:`vmware-esxi-preconfigured-cl-image` .. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html diff --git a/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst b/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst index 04b123c9..1828cf2f 100644 --- a/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst +++ b/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst @@ -21,13 +21,9 @@ Manually installing |CL| on a new VM gives additional configuration flexibility during installation. For example: alternate disk sizes, number of partitions, pre-installed bundles, etc. -If you prefer to use a pre-configured |CL| VMware image instead, refer to -:ref:`vmware-esxi-preconfigured-cl-image`. - .. note:: - VMware also offers a type 2 hypervisor designed for the desktop environment, - called `VMware Workstation Player`_. Refer to :ref:`vmw-player-preconf` or + VMware also offers a type 2 hypervisor designed for the desktop environment, called `VMware Workstation Player`_. Refer to :ref:`vmw-player` for more information. Visit :ref:`image-types` to learn more about all available images. @@ -277,12 +273,6 @@ After configuring the settings above, power on the VM. Figure 16: VMware ESXi - Navigator > Virtual Machines > Power on VM -Related topics -************** - -* :ref:`vmware-esxi-preconfigured-cl-image` - - .. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html .. _VMware Workstation Player: https://www.vmware.com/products/workstation-player.html .. _image: https://cdn.download.clearlinux.org/image/ diff --git a/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst b/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst deleted file mode 100644 index 6ceac052..00000000 --- a/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. _vmware-esxi-preconfigured-cl-image: - -|CL-ATTR| on VMware\* ESXi (pre-configured image) -################################################# - -This page explains how to deploy a pre-configured |CL| VMware -:abbr:`VM (Virtual Machine)` image on a VMware ESXi 6.5 host. - -.. contents:: - :local: - :depth: 1 - -Overview -******** - -`VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top -of server hardware. With VMware ESXi, you can create, configure, manage, -and run |CL-ATTR| virtual machines at scale. - -We provide a pre-configured |CL| VMware image that can be run on a VMware ESXi -6.5 host. - -If manual installation is preferred, refer to :ref:`vmware-esxi-install-cl`. - -.. note:: - - VMware also offers a type 2 hypervisor designed for the desktop environment, - called `VMware Workstation Player`_. Refer to :ref:`vmw-player-preconf` or - :ref:`vmw-player` for more information. - -Download the latest |CL| VMware image -************************************* - -Get the latest |CL| VMware prebuilt image from the `image`_ repository. -Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use -this command: - -.. code-block:: bash - - curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep vmware) - -Visit :ref:`image-types` for additional information about all available |CL| images. - -We also provide instructions for downloading and verifying a Clear Linux ISO. -For more information, refer to :ref:`download-verify-decompress`. - -Upload the |CL| image to the VMware server -****************************************** - -Once the |CL| VMware prebuilt image has been downloaded and -decompressed on your local system, it must be uploaded to a datastore -on the VMware ESXi server. - -The steps in this section can also be referenced from the VMware documentation -`Using Datastore File Browser in the VMware Host Client`_. - -#. Connect to the VMware ESXi server and login to an account with sufficient - permission to create and manage VMs. - -#. Under the :guilabel:`Navigator` window on the left side, - select :guilabel:`Storage`. - See Figure 1 - -#. Under the :guilabel:`Datastores` tab, click - the :guilabel:`Datastore browser` button. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png - :scale: 100 % - :alt: VMware ESXi - Navigator > Storage - - Figure 1: VMware ESXi - Navigator > Storage - -#. Click the :guilabel:`Create directory` button and name the directory - `Clear Linux VM`. See Figure 2. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-2.png - :scale: 100 % - :alt: VMware ESXi - Datastore > Create directory - - Figure 2: VMware ESXi - Datastore > Create directory - -#. Select the newly-created directory and click the :guilabel:`Upload` - button. See Figure 3. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-3.png - :scale: 100 % - :alt: VMware ESXi - Datastore > Upload VMware image - - Figure 3: VMware ESXi - Datastore > Upload VMware image - -#. Select the decompressed |CL| VMware image file - :file:`clear-[version number]-vmware.vmdk` and upload it. - -Convert the |CL| image to an ESXi-supported format -************************************************** - -Once the |CL| VMware prebuilt image has been uploaded to the VMware ESXi -datastore, it must be converted to a format for use with VMware's ESXi -hypervisor. - -The steps in this section can also be referenced from the VMware documentation on `Cloning and converting virtual machine disks with vmkfstools`_ - -#. SSH into the `vSphere Management Assistant`_ appliance that is managing - the ESXi host or connect to the vSphere hosting using the `vSphere CLI`_. - - .. note:: - - If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available, - you can temporarily enable SSH directly on the ESXi host by following the - steps described in `Enable the Secure Shell (SSH) in the VMware Host Client`_. - - As a security best practice, remember to disable SSH access after following the steps in this section. - - -#. Locate the uploaded image, which is typically found in - :file:`/vmfs/volumes/datastore1`. - -#. Use the :command:`vmkfstools` command to perform the conversion, as - shown below: - - .. code-block:: console - - vmkfstools -i clear-[version number]-vmware.vmdk -d zeroedthick clear-[version number]-esxi.vmdk - - Two files should result from this: - - * :file:`clear-[version number]-esxi-flat.vmdk` - * :file:`clear-[version number]-esxi.vmdk` - - The :file:`clear-[version number]-esxi.vmdk` file will be used in the - next section when you create a new VM. - -Create and configure a new VM -***************************** - -In this section, you will create a new VM, configure its basic parameters -such as number of CPUs, memory size, and then attach the converted |CL| -VMware image. Also, in order to boot |CL|, you must enable UEFI support. - -#. Under the :guilabel:`Navigator` window, select - :guilabel:`Virtual Machines`. See Figure 4. - -#. In the right window, click the :guilabel:`Create / Register VM` button. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-4.png - :scale: 100 % - :alt: VMware ESXi - Navigator > Virtual Machines - - Figure 4: VMware ESXi - Navigator > Virtual Machines - -#. On the :guilabel:`Select creation type` step: - - #. Select the :guilabel:`Create a new virtual machine` option. See - Figure 5. - - #. Click the :guilabel:`Next` button. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-5.png - :scale: 100 % - :alt: VMware ESXi - Create a new virtual machine - - Figure 5: VMware ESXi - Create a new virtual machine - -#. On the :guilabel:`Select a name and guest OS` step: - -#. Give the new VM a name in the :guilabel:`Name` field. See Figure 6. - -#. Set the :guilabel:`Compatibility` option to - :guilabel:`ESXi 6.5 virtual machine`. -#. Set the :guilabel:`Guest OS family` option to :guilabel:`Linux`. -#. Set the :guilabel:`Guest OS version` option to - :guilabel:`Other 3.x or later Linux (64-bit)`. -#. Click the :guilabel:`Next` button. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-6.png - :scale: 100 % - :alt: VMware ESXi - Give a name and select guest OS type - - Figure 6: VMware ESXi - Give a name and select guest OS type - -#. On the :guilabel:`Select storage` step: - - #. Accept the default option. - #. Click the :guilabel:`Next` button. - -#. On the :guilabel:`Customize settings` step: - - #. Click the :guilabel:`Virtual Hardware` button. See Figure 7. - #. Expand the :guilabel:`CPU` setting and enable - :guilabel:`Hardware virtualization` by checking - :guilabel:`Expose hardware assisted virtualization to the guest OS`. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png - :scale: 100 % - :alt: VMware ESXi - Enable hardware virtualization - - Figure 7: VMware ESXi - Enable hardware virtualization - - #. Remove the default :guilabel:`Hard drive 1` setting by clicking - the `X` icon on the right side. See Figure 8. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-8.png - :scale: 100 % - :alt: VMware ESXi - Remove hard drive - - Figure 8: VMware ESXi - Remove hard drive - - #. Since a pre-configured image will be used, - the :guilabel:`CD/DVD Drive 1` setting will not be needed. Disable it - by unchecking the :guilabel:`Connect` checkbox. See Figure 9. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png - :scale: 100 % - :alt: VMware ESXi - Disconnect the CD/DVD drive - - Figure 9: VMware ESXi - Disconnect the CD/DVD drive - - #. Attach the :file:`clear-[version number]-esxi.vmdk` file that was - converted from the pre-configured |CL| VMware image. - - #. Click the :guilabel:`Add hard disk` button and select the - :guilabel:`Existing hard drive` option. See Figure 10. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-10.png - :scale: 100 % - :alt: VMware ESXi - Add an existing hard drive - - Figure 10: VMware ESXi - Add an existing hard drive - - #. Select the converted :file:`clear-[version number]-esxi.vmdk` - file. Do not use the original unconverted - :file:`clear-[version number]-vmware.vmdk` file. See Figure 11. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png - :scale: 100 % - :alt: VMware ESXi - Select the converted `vmdk` file - - Figure 11: VMware ESXi - Select the converted - :file:`clear-[version number]-esxi.vmdk` file - -#. |CL| needs UEFI support in order to boot. Enable UEFI boot support. - - #. Click the :guilabel:`VM Options` button. See Figure 12. - #. Expand the :guilabel:`Boot Options` setting. - #. For the :guilabel:`Firmware` setting, click the drop-down list to - the right of it and select the :guilabel:`EFI` option. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-12.png - :scale: 100 % - :alt: VMware ESXi - Set boot firmware to EFI - - Figure 12: VMware ESXi - Set boot firmware to EFI - -#. Click the :guilabel:`Save` button. -#. Click the :guilabel:`Next` button. -#. Click the :guilabel:`Finish` button. - -Power on the VM and boot |CL| -***************************** - -After configuring the settings above, power on the VM. - -#. Under the :guilabel:`Navigator` window, select - :guilabel:`Virtual Machines`. See Figure 13. -#. In the right window, select the newly-created VM. -#. Click the :guilabel:`Power on` button. -#. Click on the icon representing the VM to bring it into view and maximize - its window. - - .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-13.png - :scale: 100 % - :alt: VMware ESXi - Navigator > Virtual Machines > Power on VM - - Figure 13: VMware ESXi - Navigator > Virtual Machines > Power on VM - -Related topics -************** - -* :ref:`vmware-esxi-install-cl` - -.. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html -.. _Using Datastore File Browser in the VMware Host Client: https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.html.hostclient.doc/GUID-7533A767-8396-4844-A3F2-206047D254EA.html -.. _vSphere Management Assistant: https://www.vmware.com/support/developer/vima/ -.. _vSphere CLI: https://www.vmware.com/support/developer/vcli/ -.. _Cloning and converting virtual machine disks with vmkfstools: https://kb.vmware.com/kb/1028042 -.. _Enable the Secure Shell (SSH) in the VMware Host Client: https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.html.hostclient.doc/GUID-B649CB74-832F-467B-B6A4-8BA67AD5C1F0.html -.. _VMware Workstation Player: https://www.vmware.com/products/workstation-player.html -.. _image: https://cdn.download.clearlinux.org/image/ diff --git a/source/guides/clear/ister.rst b/source/guides/clear/ister.rst index b71aa8cc..21e2b6af 100644 --- a/source/guides/clear/ister.rst +++ b/source/guides/clear/ister.rst @@ -86,7 +86,6 @@ Related topics ************** * :ref:`mixer` -* :ref:`bulk-provision` .. _ister.py: https://github.com/bryteise/ister .. _Current release: https://cdn.download.clearlinux.org/current/ diff --git a/source/guides/maintenance/bulk-provision.rst b/source/guides/maintenance/bulk-provision.rst deleted file mode 100644 index a609fa6a..00000000 --- a/source/guides/maintenance/bulk-provision.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _bulk-provision: - -Bulk provision -############## - -This guide explains how to perform a bulk provision of |CL-ATTR| using a -combination of the |CL| installer, Ister, and -:abbr:`ICIS (Ister Cloud Init Service)`. - -.. contents:: - :local: - :depth: 1 - -Overview -******** - -To configure a bulk provision: - -* Define Ister configuration files to customize the installation process -* Define cloud-init\* files to customize the installation instance -* Host the configuration files in ICIS to allow Ister to use them during - the installation - -Figure 1 depicts the flow of information between a PXE server and a PXE -client that needs to be set up to perform a bulk provision. - -.. figure:: ./figures/bulk-provision-flow.png - :alt: Bulk provision information flow - - Figure 1: Bulk provision information flow - -Prerequisites -************* - -Before performing a bulk provision, verify you have a PXE server capable -of performing network boots of |CL|. Please refer to our -:ref:`guide on how to perform an iPXE boot` using -:abbr:`NAT (network address translation)` for details. - -Because a bulk provision relies on a reboot, ensure the following -preparations have been made: - -* No existing disks are bootable. -* The network boot option must come immediately after the disk boot option - on any computer performing the installation. - -Configuration -************* - -#. Install ICIS by following the getting started guide on the - `ICIS`_ GitHub\* repository. - -#. Create an Ister installation file and save it to the - :file:`static/ister` directory within the web hosting directory for - ICIS. The installation file is a JSON block and provides Ister - with the steps it needs to perform an installation. The file outlines - what partitions, file systems, and mount points Ister should set - up. Lastly, the file outlines which bundles to install. See our - :ref:`bundles` document for the list of available bundles. The - following example shows the contents of an Ister installation file: - - .. code-block:: json - - { - "DestinationType":"physical", - "PartitionLayout":[ - {"disk":"sda", "partition":1, "size":"512M", "type":"EFI"}, - {"disk":"sda", "partition":2, "size":"512M", "type":"swap"}, - {"disk":"sda", "partition":3, "size":"rest", "type":"linux"} - ], - "FilesystemTypes":[ - {"disk":"sda", "partition":1, "type":"vfat"}, - {"disk":"sda", "partition":2, "type":"swap"}, - {"disk":"sda", "partition":3, "type":"ext4"} - ], - "PartitionMountPoints":[ - {"disk":"sda", "partition":1, "mount":"/boot"}, - {"disk":"sda", "partition":3, "mount":"/"} - ], - "Version":"latest", - "Bundles":[ - "kernel-native", - "os-core", - "os-core-update", - "os-cloudguest" - ], - "IsterCloudInitSvc":"http://192.168.1.1:60000/icis/" - } - - .. important:: - - Every Ister installation file hosted on ICIS must contain the - the `IsterCloudInitSvc` parameter as well as the :command:`os-cloudguest` - bundle. These entries allow Ister to customize an instance of of an - install. - -#. Create an Ister configuration file to define the location of the - Ister installation file. Save it to the :file:`static/ister` directory - within the web hosting directory of ICIS. The following example shows - an Ister configuration file: - - .. code-block:: none - - template=http://192.168.1.1:60000/icis/static/ister/ister.json - -#. Modify the iPXE boot script by adding a kernel parameter to the command line - for booting the network image. Add the kernel parameter `isterconf` with - the location of the Ister configuration file hosted on ICIS as the - kernel parameter value. The following example shows an iPXE boot script - with the `isterconf` parameter: - - .. code-block:: none - - #!ipxe - kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug tsc=reliable no_timer_check noreplace-smp rw initrd=initrd isterconf=http://192.168.1.1:60000/icis/static/ister/ister.conf - initrd initrd - boot - - .. note:: - - After the network image of |CL| boots, Ister inspects the - parameters used during boot in :file:`/proc/cmdline` to find the - location of the Ister configuration file. - -#. Write a cloud-init document to customize the instance of the installation - according to your requirements. The `cloud-init`_ documentation provides a - guide on how to write a cloud-init document. The guide covers the - customization options provided by cloud-init after an installation. - -#. Save the cloud-init document to the :file:`static/roles` directory within - the web hosting directory for ICIS with the name of a role you would - like to create. For example, a role may be "database", "web", or "ciao". - -#. After creating the roles, also known as cloud-init files, assign roles to - MAC addresses of PXE clients. To do so, modify the :file:`config.txt` file - in the :file:`static` directory within the web hosting directory of ICIS. - The following example shows an example assignment: - - .. code-block:: none - - # MAC address,role - 00:01:02:03:04:05,ciao - - If MAC addresses of PXE clients are not listed within the - :file:`config.txt` file, a default role for those MAC address may be - defined as follows: - - .. code-block:: none - - # MAC address,role - default,ciao - -#. Verify the following URLs are accessible on your local network: - - * \http://192.168.1.1:60000/icis/static/ister/ister.conf - * \http://192.168.1.1:60000/icis/static/ister/ister.json - * \http://192.168.1.1:60000/icis/get_config/ - * \http://192.168.1.1:60000/icis/get_role/ - * \http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt - -#. Power on the PXE client and watch it boot and install |CL|. - -#. Power-cycle the PXE client and watch it customize the |CL| installation. - -**Congratulations!** You have successfully performed a bulk provision of |CL|. - - -.. _ICIS: - https://github.com/clearlinux/ister-cloud-init-svc - -.. _cloud-init: - https://cloudinit.readthedocs.io diff --git a/source/guides/maintenance/deploy-at-scale.rst b/source/guides/maintenance/deploy-at-scale.rst index 3c5270c8..617b265e 100644 --- a/source/guides/maintenance/deploy-at-scale.rst +++ b/source/guides/maintenance/deploy-at-scale.rst @@ -221,7 +221,7 @@ through the *os-cloudguest* bundles which allow you to configure many Day 1 tasks such as setting hostname, creating users, or placing SSH keys in an automated way at boot. For more information on automating configuration during deployment of |CL| endpoints see the -:ref:`bulk-provision` guide. +:ref:`ipxe-install` guide. A configuration management tool is useful for maintaining consistent system and application-level configuration. Ansible\* is offered through the @@ -252,4 +252,4 @@ challenges your monitoring systems, and business continuity plans. server for this purpose, however implementation details are not in the scope of this document. In general, they should be close to your endpoints, highly available, and easy to scale with a load balancer when - necessary. \ No newline at end of file + necessary. diff --git a/source/guides/maintenance/developer-workstation.rst b/source/guides/maintenance/developer-workstation.rst index 2e487536..fc0e3ab6 100644 --- a/source/guides/maintenance/developer-workstation.rst +++ b/source/guides/maintenance/developer-workstation.rst @@ -17,67 +17,183 @@ other Linux\* distributions. Workstation Setup ***************** -After installing the minimum set of bundles required to get started, you can add -more bundles relevant to your specific use case. +After installing the minimum set of bundles required to get started, you can +add more bundles relevant to your specific use case. -To run any process required for |CL| development, you can add the large bundle -:ref:`*os-clr-on-clr* `. However, given how many packages this -bundle contains, you may want to deploy a leaner OS with only bundles relevant to -your project. +To run any process required for |CL| development, you can add the large +bundle :ref:`*os-clr-on-clr* `. However, you may want to deploy a leaner OS with only bundles relevant to your project. -Use Table 1, *Developer Profiles*, to identify the *minimum -required bundles* to get started developing based on your role or project. -While your role may not neatly fit in one of these categories, consider -Table 1 as a starting point. +Use the **Developer Profiles** tabs to start installing *suggested bundles* +based on your role or project. Installing any ``dkms`` bundle gives all the +tools you need to start. Consider these profiles as a starting point. -.. list-table:: **Table 1. Developer Profiles** - :widths: 20, 20, 20, 20 - :header-rows: 1 +.. tip:: + + Click on a bundle to learn how to install it using :command:`swupd`. - * - |CL| Bundle - - *Internet of Things (IoT)* - - *System Administrator* - - *Client/Cloud/Web Developer* +.. tabs:: - * - :command:`editors` - - ✓ - - ✓ - - ✓ + .. tab:: AI/ML Engineer - * - :command:`network-basic` - - ✓ - - ✓ - - ✓ + .. list-table:: + :widths: 50, 50 + :header-rows: 1 - * - :command:`openssh-server` - - ✓ - - ✓ - - ✓ + * - Function + - Bundle - * - :command:`webserver-basic` - - - - ✓ - - ✓ + * - Build machine learning applications with a full suite of libraries. + - `machine-learning-basic `_ - * - :command:`application-server` - - - - ✓ - - ✓ + * - Build machine learning applications with PyTorch, an optimized tensor library for deep learning. + - `machine-learning-pytorch `_ - * - :command:`database-basic` - - - - ✓ - - ✓ + * - Build machine learning applications using Tensorflow, a library for numerical computation using deep neural networks. + - `machine-learning-tensorflow `_ - * - :command:`desktop-autostart` - - ✓ - - ✓ - - ✓ + * - Web-based, interactive tools for machine learning. + - `machine-learning-web-ui `_ - * - :command:`dev-utils` - - - - - - ✓ + * - Machine learning Docker container. + - `machine-learning `_ + + * - Pre-built Python libraries for Data Science. + - `python-extras `_ + + * - API helper for cloud access. + - `cloud-api `_ + + .. tab:: Computer Vision Engineer + + .. list-table:: + :widths: 50, 50 + :header-rows: 1 + + * - Function + - Bundle + + * - Build computer vision applications. + - `computer-vision-basic `_ + + * - Work with deep learning and edge-optimized models. + - `computer-vision-models `_ + + * - Basic OpenVINO™ toolkit. + - `computer-vision-openvino `_ + + * - API helper for cloud access. + - `cloud-api `_ + + * - Run container applications from Dockerhub in lightweight virtual machines. + - `containers-virt `_ + + * - All content for pkgconfig file opencv.pc. + - `devpkg-opencv `_ + + * - *Refer also to Cloud Orchestration Engineer* + - + + .. tab:: Cloud Orchestration Engineer + + .. list-table:: + :widths: 50, 50 + :header-rows: 1 + + * - Function + - Bundle + + * - Contains Clear Linux\* OS native software for cloud. + - `ethtool `_ + + * - Utilities for controlling TCP/IP networking and traffic control. + - `iproute2 `_ + + * - API helper for cloud access. + - `cloud-api `_ + + * - C++ runtime support. + - `libstdcpp `_ + + * - Load and enumerate PKCS#11 modules. + - `p11-kit `_ + + .. tab:: Kernel Developer + + .. list-table:: + :widths: 50, 50 + :header-rows: 1 + + * - Function + - Bundle + + * - Installs kernel, initrd, kernel config, system map; creates a bootloader entry. + - `kernel-install `_ + + * - Support module for building/loading via Dynamic Kernel Module System (DKMS) in LTS kernel. + - `kernel-lts-dkms `_ + + * - Support module for building/loading via Dynamic Kernel Module System (DKMS) in native kernel. + - `kernel-native-dkms `_ + + * - Support module for building/loading via Dynamic Kernel Module System (DKMS) in AWS kernel. + - `kernel-aws-dkms `_ + + * - Run the Kernel-based Virtual Machine (KVM) with |CL| as a guest under KVM. + - `kernel-kvm `_ + + * - Linux Test Project. + - `ltp `_ + + .. tab:: Maker Developer + + .. list-table:: + :widths: 50, 50 + :header-rows: 1 + + * - Function + - Bundle + + * - Basic tools for makers and experimenters. + - `maker-basic `_ + + * - GIS/Mapping tools for makers. + - `maker-gis `_ + + * - Electronic Design Tool. + - `Fritzing `_ + + * - Open-source electronics prototyping platform. + - `arduino-ide `_ + + .. tab:: System Administrator + + .. list-table:: + :widths: 50, 50 + :header-rows: 1 + + * - Function + - Bundle + + * - Run popular terminal text editors. + - `editors `_ + + * - Run network utilities and modify network settings. + - `network-basic `_ + + * - Run a secure shell (SSH) server for access from remote machines. + - `openssh-server `_ + + * - Run a HTTP web server. + - `web-server-basic `_ + + * - Run an application server via HTTP. + - `application-server `_ + + * - Run an SQL database. + - `database-basic `_ + + * - Bundle to automatically launch the GUI upon boot. + - `desktop-autostart `_ swupd search ************ @@ -101,8 +217,8 @@ developing your project. * :ref:`Mixer ` * :ref:`Autospec ` -Other resources for developers ------------------------------------ +Related topics +-------------- * `Developer Tooling Framework`_ for |CL| * `Bundle Definition Files`_ diff --git a/source/guides/maintenance/download-verify-decompress.rst b/source/guides/maintenance/download-verify-decompress.rst index 1dc74083..9142bc34 100644 --- a/source/guides/maintenance/download-verify-decompress.rst +++ b/source/guides/maintenance/download-verify-decompress.rst @@ -142,7 +142,7 @@ checksum file designated with the suffix `-SHA512SUMS`. .. code-block:: bash - CertUtil -hashfile ./clear-[version number]-[image type].[compression type] sha512 + CertUtil -hashfile ./clear-[version number]-[image type].[compression type] SHA512 #. Manually compare the output with the original checksum value shown in the downloaded checksum file and make sure they match. @@ -173,4 +173,4 @@ Image types .. include:: ../../reference/image-types.rst :start-after: incl-image-filename-end: -.. _image: https://clearlinux.org/downloads \ No newline at end of file +.. _image: https://clearlinux.org/downloads diff --git a/source/guides/maintenance/figures/bulk-provision-flow.png b/source/guides/maintenance/figures/bulk-provision-flow.png deleted file mode 100644 index 036982f7..00000000 Binary files a/source/guides/maintenance/figures/bulk-provision-flow.png and /dev/null differ diff --git a/source/guides/maintenance/fix-broken-install.rst b/source/guides/maintenance/fix-broken-install.rst index 5515b697..58f4c824 100644 --- a/source/guides/maintenance/fix-broken-install.rst +++ b/source/guides/maintenance/fix-broken-install.rst @@ -3,8 +3,7 @@ Fix a broken installation ######################### -This guide explains how to fix a broken installation of |CL-ATTR| using a live -desktop image on a USB. +This guide explains how to fix a broken installation of |CL-ATTR| using a live desktop image on a USB. .. contents:: :local: @@ -17,25 +16,21 @@ This guide assumes you have installed |CL| on a target system, but the OS does not boot or function properly. The process described in this guide can only verify and fix files that -:ref:`swupd` owns in :file:`/usr`. Files outside of this path, such -as :file:`/home/`, :file:`/etc`, :file:`/var`, etc., cannot be repaired by this -process. +:ref:`swupd` owns in :file:`/usr` and :file:`/var`. Files outside of this path, such as :file:`/home/`, :file:`/etc`, etc., cannot be repaired by this process. Prerequisites ************* -* Download and install the live desktop image on a USB. See - :ref:`bare-metal-install-desktop` for install instructions. +* Download and burn the live desktop image on a USB. + See :ref:`bare-metal-install-desktop` for instructions. Boot a live desktop image to fix target system ********************************************** #. Boot the |CL| live desktop image. -.. include:: ../../get-started/bare-metal-install-desktop.rst - :start-after: install-on-target-start: - :end-before: install-on-target-end: - +#. Select |CL| in the boot menu. + Mount root partition, verify, and fix ************************************* @@ -49,11 +44,11 @@ Mount root partition, verify, and fix .. code-block:: bash - lsblk + lsblk -o NAME,LABEL,PARTTYPE,PARTLABEL We'll use :file:`/dev/sda3/` as the root partition example. - #. Next, mount the partition to the :file:`/mnt` folder. + #. Next, mount the root partition to the :file:`/mnt` folder. .. code-block:: bash diff --git a/source/guides/network/dpdk.rst b/source/guides/network/dpdk.rst index 81712e01..5072c4ad 100644 --- a/source/guides/network/dpdk.rst +++ b/source/guides/network/dpdk.rst @@ -171,7 +171,7 @@ cables as shown in figure 2. .. figure:: ./figures/pyshical_net.png - Figure 2: Physical network environment + Figure 2: Physical network environment Run l3fwd application (Platform B) diff --git a/source/guides/network/figures/network-boot-flow.png b/source/guides/network/figures/network-boot-flow.png deleted file mode 100644 index 7ad68c76..00000000 Binary files a/source/guides/network/figures/network-boot-flow.png and /dev/null differ diff --git a/source/guides/network/figures/network-boot-setup.png b/source/guides/network/figures/network-boot-setup.png deleted file mode 100644 index dc9239db..00000000 Binary files a/source/guides/network/figures/network-boot-setup.png and /dev/null differ diff --git a/source/guides/network/ipxe-install.rst b/source/guides/network/ipxe-install.rst deleted file mode 100644 index 1c397072..00000000 --- a/source/guides/network/ipxe-install.rst +++ /dev/null @@ -1,342 +0,0 @@ -.. _ipxe-install: - -Install over the network with iPXE -################################## - -This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot -Execution Environment)` over the network. - -.. contents:: - :local: - :depth: 1 - -Overview -******** - -PXE is an industry standard that describes client-server interaction with -network-boot software and uses the DHCP and TFTP protocols. This guide shows one -method of using the PXE environment to install |CL|. - -The PXE extension called `iPXE`_ adds support for additional protocols such as -HTTP, :abbr:`iSCSI (Internet Small Computer Systems Interface)`, :abbr:`AoE -(ATA over Ethernet\*)`, and :abbr:`FCoE (Fiber Channel over Ethernet\*)`. iPXE -enables network booting on computers with no built-in PXE support. - -To install |CL| through iPXE, you must create a PXE client. Figure 1 depicts -the flow of information between a PXE server and a PXE client. - -.. figure:: ./figures/network-boot-flow.png - :alt: PXE information flow - - Figure 1: PXE information flow. - -.. caution:: - - The |CL| image that boots through the PXE process automatically erases all - data and partitions on the PXE client system and creates 3 new partitions - to install onto. - -Prerequisites -************* - -Before booting with iPXE, make the following preparations. - -Your PXE client system must meet the requirements to run |CL| and have a boot -order where the network boot option is prioritized before the disk boot -option. To determine if your PXE client system meets the minimum requirements -for |CL|, review the :ref:`compatibility-check`. - -Connect the PXE server and PXE clients to a switch on a private network, as -shown in figure 2. - -.. figure:: ./figures/network-boot-setup.png - :alt: Network topology - - Figure 2: Network topology. - -Your PXE server must have: - -* Ethernet/LAN boot option. -* At least two network adapters. -* Connection to a public network. -* Secure boot option disabled. - -.. note:: - - You must disable the secure boot option in the BIOS because the UEFI - binaries used to boot |CL| are not signed. - - -Configuration -************* - -To set up |CL| using iPXE automatically, use the :file:`configure-ipxe.sh` -script included with :abbr:`ICIS (Ister Cloud Init Service)`. For additional -instructions on the script, refer to the guide on the `ister-cloud-init-svc`_ -GitHub\* repository. - -To set up |CL| manually, perform the steps below. - -#. Define the variables used for iPXE boot configuration. - - .. code-block:: console - - ipxe_app_name=ipxe - ipxe_port=50000 - web_root=/var/www - ipxe_root=$web_root/$ipxe_app_name - tftp_root=/srv/tftp - external_iface=eno1 - internal_iface=eno2 - pxe_subnet=192.168.1 - pxe_internal_ip=$pxe_subnet.1 - pxe_subnet_mask_ip=255.255.255.0 - pxe_subnet_bitmask=16 - -#. Log in and get root privilege. - - .. code-block:: bash - - sudo -s - -#. Add the :command:`pxe-server` bundle to your |CL| system. The bundle contains all - files needed to run a PXE server. - - .. code-block:: bash - - sudo swupd bundle-add pxe-server - -#. Download the latest network-bootable release of |CL| and extract the - files. - - .. code-block:: bash - - sudo mkdir -p $ipxe_root - sudo curl -o /tmp/clear-pxe.tar.xz \ - https://cdn.download.clearlinux.org/current/clear-$(curl \ - https://cdn.download.clearlinux.org/latest)-pxe.tar.xz - sudo tar -xJf /tmp/clear-pxe.tar.xz -C $ipxe_root - sudo ln -sf $(ls $ipxe_root | grep 'org.clearlinux.*') $ipxe_root/linux - - .. note:: - - Ensure that the initial ramdisk file is named :file:`initrd` and - the kernel file is named :file:`linux`, which is a symbolic link to the - actual kernel file. - -#. Create an iPXE boot script with the following contents. During an iPXE - boot, the iPXE boot script directs the PXE client to download the files to - boot and install |CL|. Use the names previously given to the initial - ramdisk and kernel files. - - .. code-block:: console - - sudo cat > $ipxe_root/ipxe_boot_script.ipxe << EOF - #!ipxe - kernel linux quiet init=/usr/lib/systemd/systemd-bootchart \ - initcall_debug tsc=reliable no_timer_check noreplace-smp rw \ - initrd=initrd - initrd initrd - boot - EOF - -#. The :command:`pxe-server` bundle contains a lightweight web-server known as - nginx. Create a configuration file for nginx to serve |CL| to PXE - clients with the following contents: - - .. code-block:: console - - sudo mkdir -p /etc/nginx/conf.d - sudo cat > /etc/nginx/conf.d/$ipxe_app_name.conf << EOF - server { - listen $ipxe_port; - server_name localhost; - location /$ipxe_app_name/ { - root $web_root; - autoindex on; - } - } - EOF - - sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf - - .. note:: - - Create a separate nginx configuration file to serve network-bootable - images on a non-standard port number. This action saves existing nginx - configurations. - -#. Start nginx and enable the startup on boot option. - - .. code-block:: bash - - sudo systemctl start nginx - sudo systemctl enable nginx - -#. The :command:`pxe-server` bundle contains a lightweight DNS server which - conflicts with the DNS stub listener provided in `systemd-resolved`. - Disable the DNS stub listener and temporarily stop `systemd-resolved`. - - .. code-block:: console - - sudo mkdir -p /etc/systemd - sudo cat > /etc/systemd/resolved.conf << EOF - [Resolve] - DNSStubListener=no - EOF - - sudo systemctl stop systemd-resolved - -#. Assign a static IP address to the network adapter for the private network - and restart `systemd-networkd` with the following commands: - - .. code-block:: console - - sudo mkdir -p /etc/systemd/network - sudo cat > /etc/systemd/network/70-internal-static.network << EOF - [Match] - Name=$internal_iface - [Network] - DHCP=no - Address=$pxe_internal_ip/$pxe_subnet_bitmask - EOF - - sudo systemctl restart systemd-networkd - -#. Configure :abbr:`NAT (Network Address Translation)` to route traffic from - the private network to the public network. This action makes the PXE - server act as a router. To make these changes persistent during reboots, save the - changes to the firewall with the following commands: - - .. code-block:: bash - - sudo iptables -t nat -F POSTROUTING - sudo iptables -t nat -A POSTROUTING -o $external_iface -j MASQUERADE - sudo systemctl enable iptables-save.service - sudo systemctl restart iptables-save.service - sudo systemctl enable iptables-restore.service - sudo systemctl restart iptables-restore.service - - .. note:: - - The firewall masks packets to make them appear as coming from the PXE - server and hides PXE clients from the public network. - -#. Configure the kernel to forward network packets to different - interfaces. Otherwise, NAT will not work. - - .. code-block:: bash - - sudo mkdir -p /etc/sysctl.d - sudo echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf - sudo echo 1 > /proc/sys/net/ipv4/ip_forward - -#. The :command:`pxe-server` bundle contains iPXE firmware images that allow computers - without an iPXE implementation to perform an iPXE boot. Create a TFTP - hosting directory and populate the directory with the iPXE firmware images - with the following commands: - - .. code-block:: bash - - sudo mkdir -p $tftp_root - sudo ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe - -#. The :command:`pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP - server known as `dnsmasq`. Create a configuration file for `dnsmasq` - to listen on a dedicated IP address for those functions. PXE clients on - the private network will use this IP address. - - .. code-block:: console - - sudo cat > /etc/dnsmasq.conf << EOF - listen-address=$pxe_internal_ip - EOF - -#. Add the options to serve iPXE firmware images to PXE clients over TFTP to - the `dnsmasq` configuration file. - - .. code-block:: console - - sudo cat >> /etc/dnsmasq.conf << EOF - enable-tftp - tftp-root=$tftp_root - EOF - -#. Add the options to host a DHCP server for PXE clients to the :file:`dnsmasq` - configuration file. - - .. code-block:: console - - sudo cat >> /etc/dnsmasq.conf << EOF - dhcp-leasefile=/var/db/dnsmasq.leases - - dhcp-authoritative - dhcp-option=option:router,$pxe_internal_ip - dhcp-option=option:dns-server,$pxe_internal_ip - - dhcp-match=set:pxeclient,60,PXEClient* - dhcp-range=tag:pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,15m - dhcp-range=tag:!pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,6h - - dhcp-match=set:ipxeboot,175 - dhcp-boot=tag:ipxeboot,http://$pxe_internal_ip:$ipxe_port/$ipxe_app_name/ipxe_boot_script.ipxe - dhcp-boot=tag:!ipxeboot,undionly.kpxe,$pxe_internal_ip - EOF - - - The configuration provides the following important functions: - - * Directs PXE clients without an iPXE implementation to the TFTP server - to acquire architecture-specific iPXE firmware images that allow them - to perform an iPXE boot. - * Activates only on the network adapter that has an IP address on the - defined subnet. - * Directs PXE clients to the DNS server. - * Directs PXE clients to the PXE server for routing via NAT. - * Divides the private network into two pools of IP addresses. One pool - is for network boot and one pool is used after boot. Each pool has - their own lease times. - -#. Create a file for `dnsmasq` to record the IP addresses it provides - to PXE clients. - - .. code-block:: bash - - sudo mkdir -p /var/db - sudo touch /var/db/dnsmasq.leases - -#. Start `dnsmasq` and enable startup on boot. - - .. code-block:: bash - - sudo systemctl enable dnsmasq - sudo systemctl restart dnsmasq - -#. Start `systemd-resolved`. - - .. code-block:: bash - - sudo systemctl start systemd-resolved - - .. note:: - - `systemd-resolved` dynamically updates the list of DNS servers for the - private network if you use the `dnsmasq` DNS server. The setup creates a - pass-through DNS server that relies on the DNS servers listed in - :file:`/etc/resolv.conf`. - -#. Power on the PXE client and watch the client boot and install |CL|. - - After booting, |CL| automatically partitions the hard drive, - installs itself, updates to the latest version, and reboots. - - -**Congratulations!** You have successfully installed and configured a PXE -server that enables PXE clients to boot and install |CL| over the network. - - -.. _iPXE: - http://ipxe.org/ - -.. _ister-cloud-init-svc: - https://github.com/clearlinux/ister-cloud-init-svc diff --git a/source/guides/network/vnc.rst b/source/guides/network/vnc.rst index c18670da..a58563c8 100644 --- a/source/guides/network/vnc.rst +++ b/source/guides/network/vnc.rst @@ -567,14 +567,14 @@ truly terminate an active VNC session, follow these steps: Encrypt VNC traffic through an SSH tunnel ***************************************** -By default, VNC traffic is not encrypted. Figure 6 shows an example warning +By default, VNC traffic is not encrypted. Figure 5 shows an example warning from RealVNC Viewer. .. figure:: ../../_figures/vnc/vnc-6.png :scale: 90 % :alt: RealVNC Viewer - Connection not encrypted warning - Figure 6: RealVNC Viewer - Connection not encrypted warning + Figure 5: RealVNC Viewer - Connection not encrypted warning To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps: @@ -659,7 +659,7 @@ For Method 3: Add the |CL| :command:`network-basic` bundle to get the :command:`netstat` command. -Figure 7 shows two VNC sessions (5901 and 5905) accepting connections from +Figure 6 shows two VNC sessions (5901 and 5905) accepting connections from any host as specified by the `0.0.0.0`'s. This is before the :command:`-localhost` option was used. @@ -667,9 +667,9 @@ any host as specified by the `0.0.0.0`'s. This is before the :scale: 100 % :alt: VNC session accepting connection from any host - Figure 7: VNC sessions (5901 and 5905) accepting connections from any host + Figure 6: VNC sessions (5901 and 5905) accepting connections from any host -Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from +Figure 7 shows two VNC sessions (5901 and 5905) only accepting connections from localhost as specified by `127.0.0.1`'s. This is after the :command:`-localhost` option was used. @@ -677,7 +677,7 @@ localhost as specified by `127.0.0.1`'s. This is after the :scale: 100 % :alt: VNC session only accepting connection from localhost - Figure 8: VNC sessions (5901 and 5905) only accepting connections from localhost + Figure 7: VNC sessions (5901 and 5905) only accepting connections from localhost Set up an SSH tunnel from your client system to your |CL| host ============================================================== @@ -720,7 +720,7 @@ Set up an SSH tunnel from your client system to your |CL| host :guilabel:`Host Name (or IP address)` field. #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`. -#. Configure the SSH tunnel. See Figure 9 for an example. +#. Configure the SSH tunnel. See Figure 8 for an example. a. Under the :guilabel:`Category` section, go to :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`. @@ -738,7 +738,7 @@ Set up an SSH tunnel from your client system to your |CL| host :scale: 100 % :alt: Putty - configure SSH tunnel - Figure 9: Putty - configure SSH tunnel + Figure 8: Putty - configure SSH tunnel #. Click the :guilabel:`Open` button. #. Enter your |CL| account password (not your VNC password). @@ -760,14 +760,14 @@ your VNC session. **On Windows and macOS using `RealVNC`:** #. Start the RealVNC viewer app. -#. Enter `localhost` and the fully-qualified VNC port number. See Figure 10 +#. Enter `localhost` and the fully-qualified VNC port number. See Figure 9 for an example. .. figure:: ../../_figures/vnc/vnc-10.png :scale: 100 % :alt: RealVNC viewer app connecting to localhost:1234 - Figure 10: RealVNC viewer app connecting to `localhost:1234` + Figure 9: RealVNC viewer app connecting to `localhost:1234` .. note:: diff --git a/source/guides/stacks/dlrs.rst b/source/guides/stacks/dlrs.rst index a828032f..80b6dd8c 100644 --- a/source/guides/stacks/dlrs.rst +++ b/source/guides/stacks/dlrs.rst @@ -557,7 +557,7 @@ This example walks through the basic instructions for using the inference engine .. code-block:: bash - docker run -p 8000:8000 stacks-tensorflow-mkl:latest bash -c ". /workspace/scripts/serve.sh && ie_serving model --model_name resnet --model_path gs://intelai_public_models/resnet_50_i8 --port 8000" + docker run -p 8000:8000 stacks-dlrs-mkl:latest bash -c ". /workspace/scripts/serve.sh && ie_serving model --model_name resnet --model_path gs://intelai_public_models/resnet_50_i8 --port 8000" Once the server is setup, use a :command:`grpc` client to communicate with served model: @@ -656,7 +656,7 @@ Your browser displays the following: :scale: 50% :alt: Jupyter Notebook -Figure 1: Jupyter Notebook + Figure 1: Jupyter Notebook To create a new notebook, click :guilabel:`New` and select :guilabel:`Python 3`. @@ -665,7 +665,7 @@ To create a new notebook, click :guilabel:`New` and select :guilabel:`Python 3`. :scale: 50% :alt: Create a new notebook -Figure 2: Create a new notebook + Figure 2: Create a new notebook A new, blank notebook is displayed, with a cell ready for input. @@ -673,7 +673,7 @@ A new, blank notebook is displayed, with a cell ready for input. :scale: 50% :alt: New blank notebook -Figure 3: New blank notebook + Figure 3: New blank notebook To verify that PyTorch is working, copy the following snippet into the blank cell, and run the cell. @@ -689,7 +689,7 @@ cell, and run the cell. :scale: 50% :alt: Sample code snippet -Figure 4: Sample code snippet + Figure 4: Sample code snippet When you run the cell, your output will look something like this: @@ -697,7 +697,7 @@ When you run the cell, your output will look something like this: :scale: 50% :alt: Code output -Figure 5: Code output + Figure 5: Code output You can continue working in this notebook, or you can download existing @@ -784,7 +784,7 @@ Compiling AIXPRT with OpenMP on DLRS To compile AIXPRT for DLRS, you will have to get the community edition of AIXPRT and update the `compile_AIXPRT_source.sh` file.AIXPRT utilizes build configuration files, so to build AIXPRT on the image, copy, the build files from the base image, this can be done by adding these commands -to the end of the stacks-tensorflow-mkl dockerfile: +to the end of the stacks-dlrs-mkl dockerfile: .. code-block:: console diff --git a/source/guides/stacks/mers.rst b/source/guides/stacks/mers.rst new file mode 100644 index 00000000..65b1a03e --- /dev/null +++ b/source/guides/stacks/mers.rst @@ -0,0 +1,407 @@ +.. _mers: + +Media Reference Stack +##################### + +The Media Reference Stack (MeRS) is a highly optimized software stack for +Intel® architecture to enable media prioritized workloads, such as transcoding and analytics. + +This guide explains how to use the pre-built |MERS| container image, build +your own |MERS| container image, and use the reference stack. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + +Finding the balance between quality and performance, understanding all of the +complex standard-compliant encoders, and optimizing across the +hardware-software stack for efficiency are all engineering and time +investments for developers. + +The Media Reference Stack (MeRS) offers a highly optimized software stack for Intel Architecture to enable media prioritized workloads, such as +transcoding and analytics. |MERS| abstracts away the complexity of +integrating multiple software components and specifically tunes them for Intel platforms. |MERS| allows media and visual cloud developers to deliver experiences using a simple containerized solution. + +Prerequisites +============= + +|MERS| can run on any host system that supports Docker\*. + +The steps in this guide use |CL-ATTR| as the host system. + +- To install |CL| on a host system, see how to + :ref:`install Clear Linux* OS from the live desktop + `. + +- To install Docker* on a |CL| host system, see + the :ref:`instructions for installing Docker* `. + +.. important:: + + For optimal performance, a processor with Vector Neural Network + Instructions (VNNI) should be used. VNNI is an extension of Intel® + Advanced Vector Extensions 512 (Intel® AVX-512) and is available starting + with the 2nd generation of Intel® Xeon® Scalable Platform, providing AI + inference acceleration. + +Stack Features +============== + +The |MERS| provides a `pre-built Docker image available on DockerHub +`_, which includes +instructions on build the image from source. |MERS| is open-sourced to ensure +developers have easy access to the source code and are able to customize it. +|MERS| is built using the *clearlinux:latest* Docker image and aims to support the latest |CL| version. + +|MERS| provides the following libraries: + +.. list-table:: + :widths: auto + + * - SVT-HEVC + - Scalable Video Technology for HEVC encoding, also known as H.265 + * - SVT-AV1 + - Scalable Video Technology for AV1 encoding + * - x264 + - x264 for H.264/MPEG-4 AVC encoding + * - MKL-DNN + - `Intel® Math Kernel Library for Deep Neural Networks `_ + +Components of the |MERS| include: + +* |CL| as a base for performance and security + +* `Intel® Distribution of OpenVINO™ toolkit + `_ for inference. + +* `FFmpeg `_ with `Scalable Video Technology (SVT) + `_ plugins for encoding, decoding, and transcoding. + +* `GStreamer `_ with `Scalable Video + Technology (SVT) `_ and `OpenVINO™ toolkit + `_ plugins for + analytics. + +.. note:: + + The pre-built |MERS| container image configures :command:`FFmpeg` without + certain elements (specific encoder, decoder, muxer, etc.) that you may + require. If you require changes to :command:`FFmpeg` we suggest starting at :ref:`building-the-mers-container-image`. + +.. note:: + + The Media Reference Stack is a collective work, and each piece of software + within the work has its own license. Please see the `MeRS Terms of Use + `_ for more details about licensing and usage of the Media Reference Stack. + + +Getting the pre-built |MERS| container image +******************************************** + +Pre-built |MERS| Docker images are available on DockerHub at +https://hub.docker.com/r/clearlinux/stacks-mers + + +To use the |MERS|: + +#. Pull the image directly from `Docker Hub + `_. + + .. code-block:: bash + + docker pull clearlinux/stacks-mers + + .. note :: + + The |MERS| docker image is large in size and will take some time to + download depending on your Internet connection. + + If you are on a network with outbound proxies, be sure to configure Docker allow access. See the `Docker service proxy + `_ and + `Docker client proxy + `_ + documentation for more details. + +#. Once you have downloaded the image, run it with: + + .. code-block:: bash + + docker run -it clearlinux/stacks-mers + + This will launch the image and drop you into a bash shell inside the + container. :command:`GStreamer` and :command:`FFmpeg` programs are + installed in the container image and accessible in the default $PATH. These programs can be used as you would normally outside of |MERS|. + + Paths to media files and video devices, such as cameras, can be shared from the host to the container with the :command:`--volume` switch + `using Docker volumes `_. + +.. _building-the-mers-container-image: + +Building the |MERS| container image from source +*********************************************** + +If you choose to build your own MeRS container image, you can optionally add +customizations as needed. The :file:`Dockerfile` for the MeRS is available on +`GitHub `_ and +can be used for reference. + +#. The |MERS| image is part of the dockerfiles repository inside the |CL| + organization on GitHub. Clone the :file:`stacks` repository. + + .. code-block:: bash + + git clone https://github.com/intel/stacks.git + +#. Navigate to the :file:`stacks/mers/clearlinux` directory which contains + the Dockerfile for the |MERS|. + + .. code-block:: bash + + cd ./stacks/mers/clearlinux + +#. Use the :command:`docker build` command with the :file:`Dockerfile` to the + MeRS container image. + + .. code-block:: bash + + docker build --no-cache -t clearlinux/stacks-mers . + +Using the |MERS| container image +******************************** + +Below are some examples of how the |MERS| container image can be used to +process media files. + +The models and video source can be substituted from your use-case. Some +publicly licensed sample videos are available at `sample-videos repsoitory +`_ for testing. + + +Example 1: Transcoding +====================== + +This example shows how to perform transcoding with :command:`FFmpeg`. + +#. On the host system, setup a workspace for data and models: + + .. code:: bash + + mkdir ~/ffmpeg + mkdir ~/ffmpeg/input + mkdir ~/ffmpeg/output + +#. Copy a video file to :file:`~/ffmpeg/input`. + + .. code:: bash + + cp ~/ffmpeg/input + +#. Run the *clearlinux/stack-mers* docker image, allowing shared access to the + workspace on the host: + + + .. code:: bash + + docker run -it \ + -v ~/ffmpeg:/home/mers-user:ro \ + clearlinux/stacks-mers:latest + + After running the :command:`docker run` command, you enter a bash shell + inside the container. + +#. From the container shell, you can run :command:`FFmpeg` against the videos + in :file:`/home/mers-user/input` as you would normally outside of |MERS|. + + For example, to transcode raw yuv420 content to SVT-HEVC and mp4: + + .. code:: bash + + ffmpeg -f rawvideo -vcodec rawvideo -s 320x240 -r 30 -pix_fmt yuv420p -i -c:v libsvt_hevc -y + + Some more generic examples of :command:`FFmpeg` commands can be found in + the `OpenVisualCloud repository + `_ and used for reference with |MERS|. + + For more information on using :command:`FFmpeg`, refer to the `FFmpeg + documentation `_. + +Example 2: Analytics +==================== + +This example shows how to perform analytics and inferences with +:command:`GStreamer`. + +The steps here are referenced from the `gst-video-analytics Getting Started +Guide `_ except simply +substituting the *gst-video-analytics* docker image for the +*clearlinux/stacks-mers* image. + +The example below shows how to use the |MERS| container image to perform +video with object detection and attributes recognition of a video using GStreamer using pre-trained models and sample video files. + +#. On the host system, setup a workspace for data and models: + + .. code:: bash + + mkdir ~/gva + mkdir ~/gva/data + mkdir ~/gva/data/models + mkdir ~/gva/data/models/intel + mkdir ~/gva/data/models/common + mkdir ~/gva/data/video + +#. Clone the opencv/gst-video-analytics repository into the workspace: + + .. code:: bash + + git clone https://github.com/opencv/gst-video-analytics ~/gva/gst-video-analytics + cd ~/gva/gst-video-analytics + git submodule init + git submodule update + +#. Clone the Open Model Zoo repository into the workspace: + + .. code:: bash + + git clone https://github.com/opencv/open_model_zoo.git ~/gva/open_model_zoo + +#. Use the Model Downloader tool of Open Model Zoo to download ready to use + pre-trained models in IR format. + + .. note:: + + If you are on a network with outbound proxies, you will need to + configure set environment variables with the proxy server. + Refer to the documentation on :ref:`proxy` for detailed steps. + + On |CL| systems you will need the *python-extras* bundle. + Use :command:`sudo swupd bundle-add python-extras` for the downloader script to work. + + .. code:: bash + + cd ~/gva/open_model_zoo/tools/downloader + python3 downloader.py --list ~/gva/gst-video-analytics/samples/model_downloader_configs/intel_models_for_samples.LST -o ~/gva/data/models/intel + + +#. Copy a video file in h264 or mp4 format to :file:`~/gva/data/video`. Any + video with cars, pedestrians, human bodies, and/or human faces can be used. + + .. code:: bash + + git clone https://github.com/intel-iot-devkit/sample-videos.git ~/gva/data/video + + This example simply clones all the video files from the `sample-videos + repsoitory `_. + +#. From a desktop terminal, allow local access to the X host display. + + .. code:: bash + + xhost local:root + + export DATA_PATH=~/gva/data + export GVA_PATH=~/gva/gst-video-analytics + export MODELS_PATH=~/gva/data/models + export INTEL_MODELS_PATH=~/gva/data/models/intel + export VIDEO_EXAMPLES_PATH=~/gva/data/video + +#. Run the *clearlinux/stack-mers* docker image, allowing shared access to + the X server and workspace on the host: + + .. code:: bash + + docker run -it --runtime=runc --net=host \ + -v ~/.Xauthority:/root/.Xauthority \ + -v /tmp/.X11-unix:/tmp/.X11-unix \ + -e DISPLAY=$DISPLAY \ + -e HTTP_PROXY=$HTTP_PROXY \ + -e HTTPS_PROXY=$HTTPS_PROXY \ + -e http_proxy=$http_proxy \ + -e https_proxy=$https_proxy \ + -v $GVA_PATH:/home/mers-user/gst-video-analytics \ + -v $INTEL_MODELS_PATH:/home/mers-user/intel_models \ + -v $MODELS_PATH:/home/mers-user/models \ + -v $VIDEO_EXAMPLES_PATH:/home/mers-user/video-examples \ + -e MODELS_PATH=/home/mers-user/intel_models:/home/mers-user/models \ + -e VIDEO_EXAMPLES_DIR=/home/mers-user/video-examples \ + clearlinux/stacks-mers:latest + + .. note:: + + In the :command:`docker run` command above: + + - :command:`--runtime=runc` specifies the container runtime to be + *runc* for this container. It is needed for correct interaction with X + server. + + - :command:`--net=host` provides host network access to container. It is + needed for correct interaction with X server. + + - Files :file:`~/.Xauthority` and :file:`/tmp/.X11-unix` mapped to the + container are needed to ensure smooth authentication with X server. + + - :command:`-v` instances are needed to map host system directories + inside Docker container. + + - :command:`-e` instances set Docker container environment variables. + Samples need them some of them set correctly to operate. Proxy variables + are needed if host is behind firewall. + + + After running the :command:`docker run` command, it will drop you into a + bash shell inside the container. + +#. From the container shell, run a sample analytics program in + :file:`~/gva/gst-video-analytics/samples` against your video source. + + Below are sample analytics that can be run against the sample videos. + Choose one to run: + + - Samples with *face detection and classification*: + + .. code:: bash + + ./gst-video-analytics/samples/shell/face_detection_and_classification.sh $VIDEO_EXAMPLES_DIR/face-demographics-walking-and-pause.mp4 + ./gst-video-analytics/samples/shell/face_detection_and_classification.sh $VIDEO_EXAMPLES_DIR/face-demographics-walking.mp4 + ./gst-video-analytics/samples/shell/face_detection_and_classification.sh $VIDEO_EXAMPLES_DIR/head-pose-face-detection-female-and-male.mp4 + ./gst-video-analytics/samples/shell/face_detection_and_classification.sh $VIDEO_EXAMPLES_DIR/head-pose-face-detection-male.mp4 + ./gst-video-analytics/samples/shell/face_detection_and_classification.sh $VIDEO_EXAMPLES_DIR/head-pose-face-detection-female.mp4 + + When running, a video with object detection and attributes recognition + (bounding boxes around faces with recognized attributes) should be + played. + + .. figure:: /_figures/stacks/mers-fig-1.png + :scale: 60% + :align: center + :alt: Face detection with the Clear Linux* OS Media Reference Stack + + Figure 1: Screenshot of |MERS| running face detection with GSTreamer + and OpenVINO. + + - Sample with *vehicle detection*: + + .. code:: bash + + ./gst-video-analytics/samples/shell/vehicle_detection_2sources_cpu.sh $VIDEO_EXAMPLES_DIR/car-detection.mp4 + + When running, a video with object detection and attributes recognition + (bounding boxes around vehicles with recognized attributes) should be + played. + + .. figure:: /_figures/stacks/mers-fig-2.png + :scale: 60% + :align: center + :alt: Vehicle detection with the Clear Linux* OS Media Reference Stack + + Figure 2: Screenshot of |MERS| running vehicle detection with + GSTreamer and OpenVINO. + + - Sample with *FPS measurement*: + + .. code:: bash + + ./gst-video-analytics/samples/shell/console_measure_fps_cpu.sh $VIDEO_EXAMPLES_DIR/bolt-detection.mp4 diff --git a/source/substitutions.txt b/source/substitutions.txt index d780b561..c3630210 100644 --- a/source/substitutions.txt +++ b/source/substitutions.txt @@ -9,3 +9,5 @@ .. |VB| replace:: VirtualBox .. |VBM| replace:: VirtualBox Manager + +.. |MERS| replace:: :abbr:`MeRS (Media Reference Stack)` diff --git a/source/tutorials/proxy.rst b/source/tutorials/proxy.rst index 0665b63c..e1a52d24 100644 --- a/source/tutorials/proxy.rst +++ b/source/tutorials/proxy.rst @@ -1,4 +1,4 @@ -.. _tutorial-proxy: +.. _proxy: Proxy configuration ###################