diff --git a/source/user-guide/lmp-auto-hostname/lmp-auto-hostname.rst b/source/user-guide/lmp-auto-hostname/lmp-auto-hostname.rst index c4bdc04a2..54b7b2dab 100644 --- a/source/user-guide/lmp-auto-hostname/lmp-auto-hostname.rst +++ b/source/user-guide/lmp-auto-hostname/lmp-auto-hostname.rst @@ -3,32 +3,24 @@ Auto Hostname ============= -This section shows how to enable the ``lmp-auto-hostname`` recipe. This recipe customizes -device hostnames at runtime, either by appending the **serial** number -from the device tree of the hardware, or the **mac address** to the hostname. +This section shows how to enable ``lmp-auto-hostname``. +This utility customizes a device's hostname at runtime, by appending it with either the **serial** number from the device tree, or the **mac address**. -The recipe lmp-auto-hostname_ is provided by meta-lmp_ and can be added by -customizing your ``meta-subscriber-overrides.git``. +The recipe for lmp-auto-hostname_ is provided by meta-lmp_ and can be added by customizing ``meta-subscriber-overrides.git``. -Enabling Recipe ---------------- +Adding the Recipe +----------------- Clone your ``meta-subscriber-overrides.git`` repo and enter its directory: .. prompt:: bash host:~$ - git clone -b devel https://source.foundries.io/factories//meta-subscriber-overrides.git + git clone https://source.foundries.io/factories//meta-subscriber-overrides.git cd meta-subscriber-overrides -Edit the ``recipes-samples/images/lmp-factory-image.bb`` file and add the recipe on the ``CORE_IMAGE_BASE_INSTALL`` list: +Edit ``recipes-samples/images/lmp-factory-image.bb``, adding the recipe to the ``CORE_IMAGE_BASE_INSTALL`` list: -.. prompt:: bash host:~$, auto - - host:~$ gedit recipes-samples/images/lmp-factory-image.bb - -**recipes-samples/images/lmp-factory-image.bb**: - -.. prompt:: text +.. code-block:: diff diff --git a/recipes-samples/images/lmp-factory-image.bb b/recipes-samples/images/lmp-factory-image.bb --- a/recipes-samples/images/lmp-factory-image.bb @@ -52,37 +44,34 @@ The ``lmp-auto-hostname`` recipe can be configured through variables. .. option:: serial - appends the serial number of the device. + Appends the serial number of the device: - **Example Result:** ``raspberrypi4-64-100000008305bbc3`` + ``raspberrypi4-64-100000008305bbc3`` .. option:: mac - appends the MAC address of a chosen network interface. + Appends the MAC address of a chosen network interface. - **Example Result:** ``raspberrypi4-64-dca6321669ea`` + ``raspberrypi4-64-dca6321669ea`` .. confval:: LMP_HOSTNAME_NETDEVICE= :default: ``eth0`` - *if* using ``mac`` mode, provide the device network interface to retrieve - a MAC address from. + If using ``mac`` mode, provide the device network interface to retrieve a MAC address from: - **Example Value:** ``eth0`` or ``wlan0`` + ``eth0`` or ``wlan0`` Configuring the LmP Auto Hostname --------------------------------- -According to your needs, select the tab serial or MAC. +Select the Serial or MAC tab below, according to your needs. .. tabs:: .. group-tab:: Serial - Serial is configured by default in the ``lmp-auto-hostname`` recipe, - no need for extra changes. - - Add the ``recipes-samples/images/lmp-factory-image.bb`` file, commit and push: + Serial is configured by default in the ``lmp-auto-hostname`` recipe, no need for extra changes. + Add the ``recipes-samples/images/lmp-factory-image.bb`` file, commit, and push: .. prompt:: bash host:~$, auto @@ -91,20 +80,18 @@ According to your needs, select the tab serial or MAC. .. group-tab:: MAC - Edit the ``conf/machine/include/lmp-factory-custom.inc`` file and add the variables: + Edit ``conf/machine/include/lmp-factory-custom.inc``, adding the variables: .. prompt:: bash host:~$, auto host:~$ gedit recipes-samples/images/lmp-factory-image.bb - **conf/machine/include/lmp-factory-custom.inc**: - - .. prompt:: text + :: LMP_HOSTNAME_MODE = "mac" LMP_HOSTNAME_NETDEVICE = "eth0" - Add the changed files, commit and push: + Add the changed files, commit, and push: .. prompt:: bash host:~$, auto @@ -113,17 +100,16 @@ According to your needs, select the tab serial or MAC. host:~$ git commit -m "lmp-auto-hostname: Adding recipe" host:~$ git push -The latest **Target** named ``platform-devel`` should be the CI job you just created. +The latest Target named ``platform-devel`` should be the CI job you just created. -When FoundriesFactory CI finishes all jobs, if your device is already registered, -wait until the Over-the-Air update finishes, otherwise download and flash the image. +If your device is already registered, when all jobs finish, wait until the Over-the-Air update completes. +Otherwise download and flash the image. Testing Auto Hostname --------------------- -Log in to the device via SSH and check the new hostname right after ``fio@``. - -Check also the file ``/etc/hostname`` to confirm the new hostname. +Log in to the device via SSH and check the new hostname (right after ``fio@``). +You can also check ``/etc/hostname`` to confirm the new hostname. .. tabs:: @@ -133,9 +119,7 @@ Check also the file ``/etc/hostname`` to confirm the new hostname. cat /etc/hostname - **Example Output**: - - .. prompt:: text + :: raspberrypi3-64-51ca7875 @@ -145,11 +129,9 @@ Check also the file ``/etc/hostname`` to confirm the new hostname. cat /etc/hostname - **Example Output**: - - .. prompt:: text + :: - raspberrypi3-64-b827ebca7875 + raspberrypi3-64-b827ebca7875 .. _meta-lmp: https://github.com/foundriesio/meta-lmp/tree/main .. _lmp-auto-hostname: https://github.com/foundriesio/meta-lmp/tree/main/meta-lmp-base/recipes-support/lmp-auto-hostname diff --git a/source/user-guide/lmp-customization/lmp-customization.rst b/source/user-guide/lmp-customization/lmp-customization.rst index 210cc4082..7705230a2 100644 --- a/source/user-guide/lmp-customization/lmp-customization.rst +++ b/source/user-guide/lmp-customization/lmp-customization.rst @@ -3,7 +3,7 @@ LmP Customization ====================== -This page covers some common ways that the Linux® microPlatform (LmP) can be modified. +This page covers common ways that the Linux® microPlatform (LmP) can be modified. This includes kernel options, startup services, user and group configuration, and other options related to the platform build. diff --git a/source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst b/source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst index fe3e3d20c..a2bd740ee 100644 --- a/source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst +++ b/source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst @@ -3,39 +3,34 @@ Auto Register ============= -This section shows how to enable the ``lmp-device-auto-register`` recipe. This -recipe creates a systemd oneshot service that will automatically register the -device on first boot once it has internet connectivity. -This is done by providing an API Token that has **devices:create** scope. +This section shows how to enable ``lmp-device-auto-register``. +This utility creates a systemd oneshot service that registers the device on first boot—once it has internet connectivity. +This is done by providing an API Token with **devices:create** scope. .. warning:: - Do not use the API Token in production. The use of an API Token is only intended for - usage in a development environment. For more information, read - :ref:`ref-factory-registration-ref`. - As customers move closer to production, do not hesitate to contact Foundries.io - to discuss the best practices to automatically register devices. + Do not use the API Token in production. + They are intended only for usage in a development environment. + For more information, read :ref:`ref-factory-registration-ref`. + When close to production, do not hesitate to contact Foundries.io™ to discuss best practices for automatically registering devices. -The recipe lmp-device-auto-register_ is provided by meta-lmp_ and can be added by -customizing your ``meta-subscriber-overrides.git``. +The recipe for lmp-device-auto-register_ is provided by meta-lmp_ and can be added by customizing your ``meta-subscriber-overrides.git``. Prerequisites ------------- To follow this section, it is important to have: -- Completed the :ref:`sec-learn` until the :ref:`gs-flash-device` section. +- Completed the getting started guide up to :ref:`gs-flash-device`. Creating Token -------------- -Go to `Tokens `_ and create a new **Api Token** by clicking on -:guilabel:`+ New Token`. +Go to `Tokens `_ and create a new **Api Token** by clicking on :guilabel:`+ New Token`. Complete with a **Description** and the **Expiration date** and select :guilabel:`next`. -Select the :guilabel:`device:create` token and -select your **Factory**. You can later revoke this access and set up a new -token once you are familiar with the :ref:`ref-api-access`. +Select the :guilabel:`device:create` token and select your **Factory**. +You can later revoke this access and set up a new token once you are familiar with the :ref:`ref-api-access`. .. figure:: /_static/userguide/lmp-device-auto-register/lmp-device-auto-register-token.png :width: 500 @@ -46,22 +41,16 @@ token once you are familiar with the :ref:`ref-api-access`. Enabling Recipe --------------- -Clone your ``meta-subscriber-overrides.git`` repo and enter its directory: +Clone your ``meta-subscriber-overrides.git`` and enter its directory: .. prompt:: bash host:~$ - git clone -b devel https://source.foundries.io/factories//meta-subscriber-overrides.git + git clone https://source.foundries.io/factories//meta-subscriber-overrides.git cd meta-subscriber-overrides -Edit the ``recipes-samples/images/lmp-factory-image.bb`` file and add the recipe on the ``CORE_IMAGE_BASE_INSTALL`` list: +Edit ``recipes-samples/images/lmp-factory-image.bb``, adding the recipe to the ``CORE_IMAGE_BASE_INSTALL`` list: -.. prompt:: bash host:~$, auto - - host:~$ gedit recipes-samples/images/lmp-factory-image.bb - -**recipes-samples/images/lmp-factory-image.bb**: - -.. prompt:: text +.. code-block:: diff diff --git a/recipes-samples/images/lmp-factory-image.bb b/recipes-samples/images/lmp-factory-image.bb --- a/recipes-samples/images/lmp-factory-image.bb @@ -78,42 +67,25 @@ Edit the ``recipes-samples/images/lmp-factory-image.bb`` file and add the recipe Configuring the LmP Auto Register --------------------------------- -Create the required directory structure for this recipe: +Create the required directory structure for the recipe: .. prompt:: bash host:~$, auto + + host:~$ mkdir -p recipes-support/lmp-device-auto-register/lmp-device-auto-register - host:~$ mkdir -p recipes-support/lmp-device-auto-register/lmp-device-auto-register +Create the ``api-token`` file and replace ```` with the scoped token created in the previous steps: -Create the ``api-token`` file and replace ```` with the scoped token -created in the previous steps: +``recipes-support/lmp-device-auto-register/lmp-device-auto-register/api-token``: -.. prompt:: bash host:~$, auto - - host:~$ gedit recipes-support/lmp-device-auto-register/lmp-device-auto-register/api-token - -**recipes-support/lmp-device-auto-register/lmp-device-auto-register/api-token**: - -.. prompt:: text +:: +Create ``lmp-device-auto-register.bbappend`` in order to give the recipe access to the ``api-token`` file. -.. note:: - - If the process of auto registration is following the :ref:`ref-fully-detached` mode, then API - token filled here can be a bogus value. It only needs this because otherwise the - ``lmp-device-register`` will try to do the OAuth flow still. - -Create the file ``lmp-device-auto-register.bbappend`` in order to give the recipe -access to the ``api-token`` file. - -.. prompt:: bash host:~$, auto - - host:~$ gedit recipes-support/lmp-device-auto-register/lmp-device-auto-register.bbappend +``recipes-support/lmp-device-auto-register/lmp-device-auto-register.bbappend``: -**recipes-support/lmp-device-auto-register/lmp-device-auto-register.bbappend**: - -.. prompt:: text +:: FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" @@ -127,40 +99,33 @@ Add the changed files, commit and push: host:~$ git commit -m "lmp-device-auto-register: Adding recipe" host:~$ git push -The latest **Target** named ``platform-devel`` should be the CI job you just created. +The latest Target should be the CI job you just created. -When FoundriesFactory CI finishes all jobs, download and flash the image. +When the CI finishes, download and flash the image. .. note:: - To get a better understanding of what is going on, one can look at the repository - lmp-device-auto-register_. In there is the Systemd Service file and the corresponding - shell script that all can be customised just like the API token file is being overwritten. + To get a better understanding of what is going on, one can look at the lmp-device-auto-register_ repo. + The Systemd Service file and corresponding shell script can be customized, just like the API token file is being overwritten. Testing Auto Register --------------------- -After booting the new image, if connected to the internet, the device -will automatically register to your FoundriesFactory. -It should be visible by navigating to the `web interface `_, clicking your **Factory** and -selecting the **Devices** tab. +After booting the new image—if connected to the internet—the device will automatically register to your Factory. +It should be visible by navigating to the `web interface `_ and selecting the **Devices** tab. .. figure:: /_static/userguide/lmp-device-auto-register/lmp-device-auto-register-device.png :width: 900 :align: center + :alt: FoundriesFactory Device Auto Registered - FoundriesFactory Device Auto Registered - -On your device, use the following command to list the ``lmp-device-auto-register`` -service: +On your device, use the following command to list the ``lmp-device-auto-register`` service: .. prompt:: bash device:~$ - systemctl list-unit-files | grep enabled | grep lmp-device-auto-register + device:~$ systemctl list-unit-files | grep enabled | grep lmp-device-auto-register -**Example Output**: - -.. prompt:: text +:: lmp-device-auto-register.service enabled enabled @@ -170,15 +135,13 @@ Verify the ``lmp-device-auto-register`` application status: device:~$ systemctl status lmp-device-auto-register -**Example Output**: - -.. prompt:: text +:: lmp-device-auto-register.service - Script to auto-register device into Factory - Loaded: loaded (/usr/lib/systemd/system/lmp-device-auto-register.service; enabled; vendor preset: enabled) - Active: active (exited) since Sun 2021-09-12 17:34:06 UTC; 5min ago - Process: 774 ExecStart=/usr/bin/lmp-device-auto-register (code=exited, status=0/SUCCESS) - Main PID: 774 (code=exited, status=0/SUCCESS) + Loaded: loaded (/usr/lib/systemd/system/lmp-device-auto-register.service; enabled; vendor preset: enabled) + Active: active (exited) since Sun 2021-09-12 17:34:06 UTC; 5min ago + Process: 774 ExecStart=/usr/bin/lmp-device-auto-register (code=exited, status=0/SUCCESS) + Main PID: 774 (code=exited, status=0/SUCCESS) .. _meta-lmp: https://github.com/foundriesio/meta-lmp/tree/main .. _lmp-device-auto-register: https://github.com/foundriesio/meta-lmp/tree/main/meta-lmp-base/recipes-support/lmp-device-auto-register diff --git a/source/user-guide/mirror-action/mirror-action.rst b/source/user-guide/mirror-action/mirror-action.rst index bc2c4ee93..ea759b8e3 100644 --- a/source/user-guide/mirror-action/mirror-action.rst +++ b/source/user-guide/mirror-action/mirror-action.rst @@ -3,26 +3,18 @@ Configuring Automatic Git Mirroring =================================== -This section shows how to configure source code mirroring to FoundriesFactory® -repositories. This helps to use external private or public ``Git`` repositories, -hosted on services such as GitHub_ or Bitbucket_. - -This focuses on setting up GitHub_ Actions and Bitbucket_ pipelines for -mirroring code, but the steps can be adapted for other ``Git`` services. +This page shows how to configure source code mirroring to the FoundriesFactory® repos. +This is useful when using external Git repositories, hosted on services such as GitHub_ or Bitbucket_. +While the focus is on setting up GitHub Actions and Bitbucket pipelines, the steps can be adapted for other hosting services. .. _ug-mirror-token: Creating Token -------------- -To allow external hosting services to access your FoundriesFactory repository, -you need to create a token. - -Create a new `API Token `_ by -clicking on :guilabel:`+ New Token`. - +To allow external hosting services to access your FoundriesFactory repo, you need to create a token. +Create a new `API Token `_ by clicking on :guilabel:`+ New Token`. Complete with a **Description** and the **Expiration date** and select :guilabel:`Next`. - Check the :guilabel:`Use for source code access` box and select your **Factory**. .. figure:: /_static/userguide/mirror-action/mirror-action.png @@ -31,19 +23,14 @@ Check the :guilabel:`Use for source code access` box and select your **Factory** Token for source code access -If Bitbucket_ is used, the token generated in the previous step is used as the -```` value. - -If GitHub_ is used, convert the token value to a base64 string and save the -output of this command. This is your ```` value. +If Bitbucket is used, the token generated in the previous step is used as the ```` value. +If GitHub is used, convert the token value to a base64 string and save the output of this command. This is your ```` value. .. prompt:: bash host:~$, auto host:~$ echo -n | base64 -w0 -**Example Output**: - -.. prompt:: text +.. code-block:: console host:~$ echo -n SQMD1Gx860mPI6jZFlLJLwaCXT5CqAaQi6nEfIfH | base64 -w0 U1FNRDFHeDg2MG1QSTZqWkZsTEpMd2FDWFQ1Q3FBYVFpNm5FZklmSA== @@ -52,10 +39,10 @@ output of this command. This is your ```` value. ```` should end with ``==`` with no carriage return. -Configuring GitHub Repository ------------------------------ +Configuring GitHub +------------------ -Go to GitHub_ and find the repository you want to mirror. +Go to GitHub and find the repository you want to mirror. Click on :guilabel:`Settings`: @@ -65,8 +52,7 @@ Click on :guilabel:`Settings`: GitHub Settings -Click on :guilabel:`Secrets` and create a new **secret** by clicking on -:guilabel:`New repository secret`. +Click on :guilabel:`Secrets` and create a new **secret** by clicking on :guilabel:`New repository secret`. .. figure:: /_static/userguide/mirror-action/mirror-action-github-secrets.png :width: 900 @@ -74,11 +60,9 @@ Click on :guilabel:`Secrets` and create a new **secret** by clicking on GitHub Secrets -The Github_ Action uses the variable ``GIT_ACCESS_TOKEN`` as the token to access -your Foundries Factory repository. +The GitHub Action uses the variable ``GIT_ACCESS_TOKEN`` as the token to access your Factory repo. -However, complete the **Name** with ``GIT_ACCESS_TOKEN`` and on **Value** paste -the ```` provided above. +However, complete the **Name** with ``GIT_ACCESS_TOKEN``, and on **Value** paste the ```` provided above. Finally, click on :guilabel:`Add secret`. @@ -91,37 +75,30 @@ Finally, click on :guilabel:`Add secret`. Creating Mirror Action ^^^^^^^^^^^^^^^^^^^^^^ -The FoundriesFactory CI only triggers builds for configured branches. This is -configured in the ``ci-scripts.git`` repository in the ``factory-config.yml`` file. +The FoundriesFactory CI only triggers builds for configured branches. +This is configured in the ``ci-scripts.git`` repository in the ``factory-config.yml`` file. Your ``factory-config.yml`` can be inspected by updating the following URL with your ````: - https://source.foundries.io/factories//ci-scripts.git/tree/factory-config.yml -Under ``lmp:`` and ``containers:`` the group ``tagging:`` shows the configured branches on ``refs/heads/:``. - -**Example**: +Under ``lmp:`` and ``containers:``, the group ``tagging:`` shows the configured branches on ``refs/heads/:``. -.. prompt:: text +.. code-block:: YAML lmp: tagging: refs/heads/main: - tag: main - refs/heads/devel: - - tag: devel ... containers: tagging: refs/heads/main: - tag: main - refs/heads/devel: - - tag: devel ... -Based on the example, FoundriesFactory CI is configured to trigger new builds -whenever a new commit is sent on ``main`` or ``devel`` branches. The following -commands, guides you to mirror the ``main`` branch. +In this example, the CI is configured to trigger new builds whenever a new commit is made to the ``main`` branch. +The following commands, guides you to mirror the ``main`` branch. .. note:: @@ -145,12 +122,6 @@ Check out the ``main`` branch. host:~$ git checkout main -In case you don't have a master branch yet, create one: - -.. prompt:: bash host:~$, auto - - host:~$ git checkout -b main - You must store workflow files in the ``.github/workflows/`` directory of your repository. .. prompt:: bash host:~$, auto @@ -159,13 +130,9 @@ You must store workflow files in the ``.github/workflows/`` directory of your re Finally, create the file ``mirror.yml`` and make sure you update the ```` with your Factory Name. -.. prompt:: bash host:~$, auto - - host:~$ gedit .github/workflows/mirror.yml - -**.github/workflows/mirror.yml**: +``.github/workflows/mirror.yml``: -.. prompt:: text +.. code-block:: YAML name: Mirroring @@ -186,12 +153,13 @@ Finally, create the file ``mirror.yml`` and make sure you update the ``/.git --all .. note:: - Make sure to provide the ``GIT_ACCESS_TOKEN`` generated in - :ref:`ug-mirror-token` and to replace ```` and ````. + Make sure to provide the ``GIT_ACCESS_TOKEN`` generated in :ref:`ug-mirror-token` and replace ```` and ````. Click on :guilabel:`Commit file` to enable this pipeline. -After this, every push to the Bitbucket_ repository mirrors all branches to -``source.foundries.io`` and triggers builds for the branches enabled in your -Factory. +After this, every push to the Bitbucket mirrors all branches to ``source.foundries.io``, and triggers builds for the branches enabled in your Factory. .. tip:: - This pipeline can be customized to mirror only specific branches as needed - for your development. + This pipeline can be customized to mirror only specific branches as needed for your development. .. _GitHub: https://github.com/ .. _Bitbucket: https://bitbucket.org