From baaed9cae6b8a8cbf6314f923f6fa747edbe7c6b Mon Sep 17 00:00:00 2001 From: "Tullis, Michael L" Date: Tue, 3 Nov 2015 12:07:10 -0700 Subject: [PATCH] Updated internal cross references in all getting started topics to use the RST :ref: syntax rather than HTML code. Also made topic headings consistent. --- .../gs-clear-containers-gettting-started.rst | 21 +++++++----- source/gs_creating_bootable_usb.rst | 25 +++++++++----- source/gs_getting_started.rst | 9 +++-- source/gs_installing_clr_as_host.rst | 33 ++++++++++++------- source/gs_running_clr_virtual.rst | 33 ++++++------------- source/gs_supported_hardware.rst | 2 ++ 6 files changed, 68 insertions(+), 55 deletions(-) diff --git a/source/gs-clear-containers-gettting-started.rst b/source/gs-clear-containers-gettting-started.rst index 04f1d1a1..b5b418ce 100644 --- a/source/gs-clear-containers-gettting-started.rst +++ b/source/gs-clear-containers-gettting-started.rst @@ -1,14 +1,17 @@ +.. _gs-clear-containers-gettting-started.rst: + Clear Containers getting started guide -====================================== +###################################### Clear Containers for Docker* Engine is now available on multiple operating systems. This enables executing existing Docker applications in the secure and fast Clear Containers environment. Binary packages ---------------- +=============== -The primary host platform is Clear Linux* Project for Intel® Architecture, version 4000 or better. However, binaries for a range of operating systems are available from: +The primary host platform is Clear Linux* Project for Intel® Architecture, version 4000 +or better. However, binaries for a range of operating systems are available from: - https://software.opensuse.org/download.html?project=home%3Aclearlinux%3Apreview&package=clear-containers-docker @@ -21,14 +24,14 @@ Currently experimental builds are available for: - Debian* 8.0 - Ubuntu* 15.04 -If you have any feedback, please mail it to the dev@lists.clearlinux.org mailing list. Subscription to this list is -available at: https://lists.clearlinux.org/mailman/listinfo/dev. +If you have any feedback, please mail it to the dev@lists.clearlinux.org mailing list. +Subscription to this list is available at: https://lists.clearlinux.org/mailman/listinfo/dev. Installation instructions -------------------------- +========================= Using hosts other than Clear Linux OS for Intel Architecture -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------------------ If you are *not* using Clear Linux OS for Intel Architecture, follow the instructions below: @@ -46,7 +49,7 @@ If you are *not* using Clear Linux OS for Intel Architecture, follow the instruc $ systemctl restart docker Using Clear Linux OS for Intel Architecture as Host -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------------------- If you are running Clear Linux OS for Intel Architecture on your host system, follow the instructions below: @@ -64,7 +67,7 @@ instructions below: $ systemctl restart docker Source Code ------------ +=========== The experimental source code is based on the Docker version 1.8.1 upstream release and is available at: diff --git a/source/gs_creating_bootable_usb.rst b/source/gs_creating_bootable_usb.rst index 90f4bc74..de9c961d 100644 --- a/source/gs_creating_bootable_usb.rst +++ b/source/gs_creating_bootable_usb.rst @@ -1,12 +1,16 @@ +.. _gs_creating_bootable_usb: + Creating a bootable USB to install the OS -========================================= +########################################## + Here's how to create a USB drive that initiates the process for -`installing Clear Linux OS for Intel Architecture as host `_. -Alternatively, you can test the OS by `running in a virtualized environment `_. +:ref:`gs_installing_clr_as_host`. Alternatively, you can test the +OS by :ref:`gs_running_clr_virtual`. What you need -------------- +============= + * A USB stick, formatted as ``ext4``. Remember that the process of flashing data to a USB completely deletes the contents of the drive; as always, run ``dd`` with caution. @@ -19,7 +23,7 @@ What you need Download and checksum ---------------------- +===================== :: @@ -27,7 +31,8 @@ $ wget https://download.clearlinux.org/image/clear-[release_number]-installer.im $ sha512sum clear-[release_number]-installer.img.xz` Confirm the mount point on the USB drive ----------------------------------------- +======================================== + Using ``$ lsblk`` is helpful to show the block-level devices; a USB drive usually shows up under ``/sdb`` or ``/sdc`` (almost never ``/sda``), and should indicate disk space approximately the size of the USB drive:: @@ -42,7 +47,8 @@ and make sure the drive isn't already mounted. The easiest way is with:: # df Flash the image to the USB --------------------------- +========================== + Flash the image with the following command, adding the ``-v`` option for verbose mode (recommended), as the image file may be large, and the process can take a while. This may need to be done as root:: @@ -50,7 +56,8 @@ may need to be done as root:: $ xzcat -v clear-[release_number]-installer.img.xz | dd of=/dev/sdb bs=4M Wait for the final confirmation -------------------------------- +=============================== + This example shows ``clear-2190-installer.img.xz`` flashed to a 16GB USB drive mounted on ``/sdc``. @@ -59,4 +66,4 @@ mounted on ``/sdc``. :alt: confirmation Success! Your USB stick is now ready to boot and initiate the process for -`installing Clear Linux OS for Intel Architecture as host `_. \ No newline at end of file +:ref:`gs_installing_clr_as_host`. \ No newline at end of file diff --git a/source/gs_getting_started.rst b/source/gs_getting_started.rst index 7430fe41..28aed9bd 100644 --- a/source/gs_getting_started.rst +++ b/source/gs_getting_started.rst @@ -1,6 +1,11 @@ +.. _gs_getting_started: + Getting started with Clear Linux* OS for Intel® Architecture ############################################################ -The easiest way to give Clear Linux OS for Intel Architecture a spin is to download a recent KVM image from the `image directory `_ on our download page. This directory contains a current image, the UEFI firmware helper and the KVM start helper script. See `running in a virtualized environment `_ for details. +The easiest way to give Clear Linux OS for Intel Architecture a spin is to download a +recent KVM image from the `image directory `_ +on our download page. This directory contains a current image, the UEFI firmware +helper and the KVM start helper script. See :ref:`gs_running_clr_virtual` for details. -You can also `install Clear Linux OS for Intel Architecture as host `_ on a target computer. \ No newline at end of file +You can also :ref:`gs_installing_clr_as_host` on a target computer. \ No newline at end of file diff --git a/source/gs_installing_clr_as_host.rst b/source/gs_installing_clr_as_host.rst index e2c225ee..637735de 100644 --- a/source/gs_installing_clr_as_host.rst +++ b/source/gs_installing_clr_as_host.rst @@ -1,29 +1,38 @@ +.. _gs_installing_clr_as_host.rst: + Installing the OS as host ########################################################## -Running Clear Linux* OS for Intel® Architecture natively on a system is easy with the simple installer image. To get started you'll need the following: +Running Clear Linux* OS for Intel® Architecture natively on a system is easy +with the simple installer image. To get started you'll need the following: -* A USB stick flashed with the `installer image `_. Instructions for how to do this are `here `_. -* Host machine running `supported hardware `_. +* A USB stick flashed with the `installer image `_. + For instructions on how to do this, see :ref:`gs_creating_bootable_usb`. +* Host machine running :ref:`gs_supported_hardware`. * Network access via DHCP. Installing Clear Linux OS for Intel Architecture to a target system -++++++++++++++++++++++++++++++++++++++++++++ +=================================================================== -1. Configure the BIOS; this may involve changing the boot device order to boot first from the USB device. -2. Insert the USB device that is flashed with the `installer image `_ into the target system, then reboot. As the system boots, you'll see:: +1. Configure the BIOS; this may involve changing the boot device order + to boot first from the USB device. +2. Insert the USB device that is flashed with the + `installer image `_ into the + target system, then reboot. As the system boots, you'll see:: - Clear Linux OS for Intel Architecture installation in progress... Your computer will power off once installation completes successfully. + Clear Linux OS for Intel Architecture installation in progress... Your + computer will power off once installation completes successfully. -The entire installation should take no more than a few minutes. If you run into any trouble, log in as root during the installation phase and check the status of the install with - -.. code:: text +The entire installation should take no more than a few minutes. If you run into +any trouble, log in as root during the installation phase and check the status +of the install with:: $ systemctl status ister You might need to switch to another TTY. -For feedback on installation or other topics, please feel free to write in to our `mailing list `_. +For feedback on installation or other topics, please feel free to write in to our +`mailing list `_. -Note: You can also `run Clear Linux OS for Intel Architecture in a virtual environment `_. +Note: You can also :ref:`gs_running_clr_virtual`. diff --git a/source/gs_running_clr_virtual.rst b/source/gs_running_clr_virtual.rst index 5fa6a97c..67ca6114 100644 --- a/source/gs_running_clr_virtual.rst +++ b/source/gs_running_clr_virtual.rst @@ -1,3 +1,5 @@ +.. _gs_running_clr_virtual: + Running in a virtualized environment ########################################################################## @@ -8,16 +10,13 @@ contains an image file, the UEFI firmware helper and the KVM start helper script. Starter script -~~~~~~~~~~~~~~ +============== To start the image, run the ``start_qemu.sh`` script from `here `_, or modify the following script for your needs and run it from the command line -with ``$ script clr_image``. +with ``$ script clr_image``:: -:: - - #!/bin/bash if [ $# -eq 0 ] ; then echo "Please provide an image to emulate as first argument" @@ -40,41 +39,29 @@ with ``$ script clr_image``. To run this script, connect from host via SSH. Take note that SSH is not enabled by default. To enable it, log in through serial console with the username ``root``. After setting the password, enable root login via SSH -by configuring ``/etc/ssh/sshd_config`` with this content: - -:: +by configuring ``/etc/ssh/sshd_config`` with this content:: PermitRootLogin yes -Now you may connect from host via SSH through 2223: - -:: +Now you may connect from host via SSH through 2223:: $ ssh -p 2223 root@localhost Alternately, there are a few other ways to approach this. -- To run the script without modifying its permissions: - - :: +- To run the script without modifying its permissions:: $ bash start_qemu.sh clr_image -- To run it as a background process: - - :: +- To run it as a background process:: $ `bash start_qemu.sh clr_image` & -- If you'd like to run the script with execute permission: - - :: +- If you'd like to run the script with execute permission:: $ chmod +x start_qemu.sh $ ./start_qemu.sh clr_image -- And to run it as a background process: - - :: +- And to run it as a background process:: $ `./start_qemu.sh clr_image` & diff --git a/source/gs_supported_hardware.rst b/source/gs_supported_hardware.rst index 0adcb7a8..a61e6e42 100644 --- a/source/gs_supported_hardware.rst +++ b/source/gs_supported_hardware.rst @@ -1,3 +1,5 @@ +.. _gs_supported_hardware: + Supported hardware ##################