new external docs

docs/howtoguides/enable-realtime.rst

@@ -0,0 +1,141 @@
+How to enable Real-time Ubuntu
+==============================
+
+Prerequisites
+-------------
+
+`Real-time Ubuntu`_ is supported on specific Ubuntu releases; see :doc:`../reference/releases`.
+
+
+Attach an Ubuntu Pro token
+--------------------------
+
+Real-time Ubuntu is available through an `Ubuntu Pro`_ security and compliance
+subscription. If you don't already have access to "Pro", it's free for personal
+use.
+
+.. important:: 
+
+   Once you enable Real-time Ubuntu, it won't be possible to enable certain
+   other Pro services. The external documentation for Pro Client describes which
+   services are `compatible with Real-time Ubuntu`_.
+
+   Real-time Ubuntu is not compatible with Livepatch. If Livepatch is enabled
+   when you install Real-time Ubuntu, Pro will offer to disable it before
+   continuing.
+
+When running this command without a token, it will generate a short code
+and prompt you to attach the machine to your Ubuntu Pro account using
+a web browser:
+
+.. code-block:: shell
+
+   sudo pro attach
+
+.. tip::
+   Set ``-h``/ ``--help`` flag to see the user manual for this or any other Pro command.
+
+Install and enable automatically
+--------------------------------
+
+The Real-time Ubuntu kernel is installed using the APT package manager. If you wish to
+access the repository but not install the package immediately, skip to `Install
+and enable manually`_.
+
+Otherwise, install Real-time Ubuntu and automatically select the right version
+for your OS and processor:
+
+.. note::
+   The different variants of the realtime kernel aren't available in every Ubuntu release.
+   Refer to :doc:`../reference/releases` for details.
+
+Choose Generic or a corresponding variant:
+
+.. tabs::
+
+   .. group-tab:: Generic
+
+      .. code-block:: shell
+
+         sudo pro enable realtime-kernel
+      
+      .. caution::
+         The generic realtime kernel is not intended for Raspberry Pi.
+         Using the Pro client to install it on these platforms will make the system unusable.
+
+   .. group-tab:: Raspberry Pi
+      For Raspberry Pi 4 and 5:
+
+      .. code-block:: shell
+
+         sudo pro enable realtime-kernel --variant=raspi
+
+   .. group-tab:: Intel IOTG
+      For 12th Gen Intel® Core™ processors:
+
+      .. code-block:: shell
+
+         sudo pro enable realtime-kernel --variant=intel-iotg
+
+You'll need to acknowledge a warning, then you should see confirmation that the
+Real-time Ubuntu package is installed:
+
+.. code-block:: text
+
+   One moment, checking your subscription first
+   Real-time kernel cannot be enabled with Livepatch.
+   Disable Livepatch and proceed to enable Real-time kernel? (y/N) y
+   Disabling incompatible service: Livepatch
+   The Real-time kernel is an Ubuntu kernel with PREEMPT_RT patches integrated.
+
+   This will change your kernel. To revert to your original kernel, you will need
+   to make the change manually.
+
+   Do you want to continue? [ default = Yes ]: (Y/n) Y
+   Updating Real-time kernel package lists
+   Updating standard Ubuntu package lists
+   Installing Real-time kernel packages
+   Real-time kernel enabled
+   A reboot is required to complete install.
+
+After rebooting, you'll be running Real-time Ubuntu.
+
+Install and enable manually
+---------------------------
+
+To access the Real-time Ubuntu repository but not install the package
+immediately, first use the ``--access-only`` flag:
+
+.. code-block:: shell-session
+
+   $ sudo pro enable realtime-kernel --access-only
+
+   One moment, checking your subscription first
+   Real-time kernel cannot be enabled with Livepatch.
+   Disable Livepatch and proceed to enable Real-time kernel? (y/N) y
+   Disabling incompatible service: Livepatch
+   Updating Real-time kernel package lists
+   Skipping installing packages: ubuntu-realtime
+   Real-time kernel access enabled
+
+.. important::
+
+   The ``--access-only`` flag was introduced in Pro Client version 27.11.
+
+Now that Real-time Ubuntu is accessible, you can install and enable it whenever
+you wish.
+
+For example, to install the generic realtime kernel (not suitable for Raspberry Pi):
+
+.. code-block:: shell
+
+   sudo apt install ubuntu-realtime
+
+
+After rebooting, you'll be running Real-time Ubuntu.
+
+
+.. LINKS
+.. _Real-time Ubuntu: https://ubuntu.com/real-time
+.. _Ubuntu Pro: https://ubuntu.com/pro
+.. _compatible with Real-time Ubuntu: https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/compatibility_matrix/