307 lines
11 KiB
ReStructuredText
307 lines
11 KiB
ReStructuredText
Disabling things
|
|
========================
|
|
|
|
.. objectives:: Objectives
|
|
|
|
In this section we will see what a disabled variable or family is, and why it can be interesting
|
|
to assign the `disabled` property to a variable or a family.
|
|
|
|
We will disable a whole family here (yes, a family can disapear in the outerspace).
|
|
|
|
.. prerequisites:: Prerequisites
|
|
|
|
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
|
|
|
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
|
|
by checking out the corresponding tag of the `rougail-tutorials` git repository.
|
|
Each tag corresponds to a stage of progress in the tutorial.
|
|
Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
|
|
|
|
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
|
|
this workshop page corresponds to the tags :tutorial:`v1.1_040 <src/tag/v1.1_040>` to :tutorial:`v1.1_044 <src/tag/v1.1_044>`
|
|
in the repository.
|
|
|
|
::
|
|
|
|
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
|
git switch --detach v1.1_040
|
|
|
|
A disabled family
|
|
---------------------------------------------
|
|
|
|
First, a definition:
|
|
|
|
.. glossary::
|
|
|
|
property
|
|
|
|
A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...)
|
|
of a family, a subfamily or a variable.
|
|
These properties change the usual behavior of a variable or family.
|
|
|
|
Here we are going to assign the `disabled` property to the `manual` family:
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml
|
|
:language: yaml
|
|
:caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file
|
|
|
|
..
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
manual:
|
|
description: Manual proxy configuration
|
|
disabled: true
|
|
|
|
http_proxy: # HTTP Proxy
|
|
|
|
address:
|
|
description: HTTP address
|
|
type: domainname
|
|
params:
|
|
allow_ip: true
|
|
|
|
port:
|
|
description: HTTP Port
|
|
type: port
|
|
default: 8080
|
|
|
|
.. raw:: html
|
|
:class: terminal
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt
|
|
|
|
..
|
|
rougail -m firefox/ -u yaml -yf config/02/config.yml
|
|
|
|
The Rougail CLI outputs this:
|
|
|
|
.. raw:: html
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/output_ro.html
|
|
:class: output
|
|
|
|
We can deduce that the `manual` family is not taken into account by Rougail.
|
|
|
|
.. glossary::
|
|
|
|
disabled
|
|
|
|
The disabled property is a property that can be assigned to a variable or a family.
|
|
It makes the :term:`configuration` act as if the variable or family that has this property has not even been defined.
|
|
It simply doesn't exist. It is deactivated for the whole configuration.
|
|
|
|
|
|
.. note:: Note that if a family has been disabled, all variables and sub-families that it contains are disabled.
|
|
|
|
If we still wanna try to assign values to variables that have been disabled:
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/config.yml
|
|
:language: yaml
|
|
:caption: Here in the :file:`config/02/config.yml` user data file, we assign values to disabled variables
|
|
|
|
If we launch the Rougail CLI:
|
|
|
|
.. raw:: html
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/cmd_ro.txt
|
|
:class: terminal
|
|
|
|
It outputs:
|
|
|
|
.. raw:: html
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html
|
|
:class: output
|
|
|
|
Let's have a look at come back to our use case, we have a choice between five options
|
|
in order to set the proxy mode:
|
|
|
|
.. image:: images/firefox_01.png
|
|
|
|
These five choices are:
|
|
|
|
- No proxy
|
|
- Auto-detect proxy settings for this network
|
|
- Use system proxy settings
|
|
- Manual proxy configuration
|
|
- Automatic proxy configuration URL
|
|
|
|
If the `Manual proxy configuration` is not selected, we don't need to set
|
|
the `address` and `port` variables, there is no point in setting them.
|
|
We could say that we disable them in order to expose the fact that we don't use them,
|
|
but it's not just that: if we fill them in, there might be a problem in the overall integrity of the configuration.
|
|
We shall fill and use in these variables in the `Manual proxy configuration` context only.
|
|
Otherwise, **we need to disable them when they are not necessary**.
|
|
|
|
If we fill them in, Rougail CLI will output a warning and the :term:`operator` will wonder : "what am I doing?".
|
|
I shall fill and use in these variables only in the `Manual proxy configuration` context.
|
|
|
|
.. important:: We need to **disable** variables or families that are not used
|
|
in a given usage context.
|
|
|
|
.. type-along:: Disabling a group of variables is disabling a family
|
|
|
|
If we don't choose the manual mode, we need to **disable** these variables.
|
|
|
|
Note that we've placed theses variables in the `http_proxy`
|
|
subfamily. We can then disable the whole `manual` subfamily in order to
|
|
disable the `http_proxy` family and all the variables that are placed in it.
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file
|
|
|
|
..
|
|
---
|
|
manual:
|
|
description: Manual proxy configuration
|
|
disabled: true
|
|
|
|
http_proxy:
|
|
description: HTTP Proxy
|
|
|
|
address:
|
|
description: HTTP address
|
|
type: domainname
|
|
params:
|
|
allow_ip: true
|
|
|
|
port:
|
|
description: HTTP Port
|
|
type: port
|
|
default: 8080
|
|
|
|
Notice the `disabled: true` parameter set in the `manual` family.
|
|
|
|
|
|
A conditional disabled family
|
|
------------------------------
|
|
|
|
.. type-along:: For those who follow the tutorial with the help of the git repository
|
|
|
|
Now you need to checkout the `v1.1_041` version::
|
|
|
|
git switch --detach v1.1_041
|
|
|
|
What we need is a *dynamic setting* of the disable/enable property of the `manual` family.
|
|
The idea in this section is to dynamically set the enable/disable tag according to the chosen context.
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled
|
|
|
|
|
|
..
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
manual:
|
|
description: Manual proxy configuration
|
|
disabled:
|
|
variable: _.proxy_mode
|
|
when_not: Manual proxy configuration
|
|
|
|
http_proxy: # HTTP Proxy
|
|
|
|
address:
|
|
description: HTTP address
|
|
type: domainname
|
|
params:
|
|
allow_ip: true
|
|
|
|
port:
|
|
description: HTTP Port
|
|
type: port
|
|
default: 8080
|
|
|
|
FIXME : trouver une autre formulation et expliquer un peu plus, notamment le "when_not"
|
|
.. note:: The `_.` Rougail's notation means the variable in the current workspace.
|
|
|
|
We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value.
|
|
|
|
As the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled.
|
|
|
|
Let's launch the Rougail CLI on an empty user value file:
|
|
|
|
.. raw:: html
|
|
:class: terminal
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/cmd_ro.txt
|
|
|
|
..
|
|
rougail -m firefox/ -u yaml -yf config/01/config.ym
|
|
|
|
We have this output:
|
|
|
|
.. raw:: html
|
|
:class: output
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html
|
|
|
|
..
|
|
<pre>╭──────────────────── Caption ─────────────────────╮
|
|
│ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #ffd700">Default value</span> │
|
|
╰──────────────────────────────────────────────────╯
|
|
Variables:
|
|
<span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">No proxy</span>
|
|
</pre>
|
|
|
|
We can see that the `manual` family and all the variables into it are not present.
|
|
|
|
.. type-along:: Dynamically enabling the `manual` family
|
|
|
|
Now if we choose **the manual mode**, that is the `Manual proxy configuration` value for the `proxy_mode`, things become slightly different.
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yaml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The `proxy_mode`'s manual setting in the :file:`config/03/config.yaml` user datas file
|
|
|
|
..
|
|
---
|
|
proxy_mode: Manual proxy configuration
|
|
manual:
|
|
http_proxy:
|
|
address: http.proxy.net
|
|
port: 3128
|
|
use_for_https: false
|
|
|
|
If the manual mode for the proxy is not selected, then the `manual` family shall be disabled.
|
|
On the other hand, if the manual proxy's configuration mode is selected,
|
|
then the `manual` family is activated (enabled).
|
|
|
|
.. note:: Remember that this activation/deactivation of the `manual` family
|
|
depends on the value of the `proxy_mode` variable.
|
|
|
|
In rougail, we can set a property's value **depending on** the value of another variable. That is, **it is conditioned by** another variable.
|
|
|
|
FIXME expliquer ici mieux le "when_not"
|
|
|
|
.. rubric:: Explanation
|
|
|
|
Here we have the `disabled` property like this:
|
|
|
|
.. code-block:: yaml
|
|
|
|
disabled:
|
|
type: variable
|
|
variable: proxy_mode
|
|
when_not: 'Manual proxy configuration'
|
|
|
|
Here the `disabled` property **depends on** the value of another variable.
|
|
The `variable` parameter allows you to define the name of the target variable on which the `disabled` property depends.
|
|
|
|
.. keypoints:: Key points progress
|
|
|
|
**summary**
|
|
|
|
We have the ability to build a contextual setting:
|
|
|
|
- if `proxy_mode` is not `'Manual proxy configuration'` the `manual` family is disabled
|
|
- if `proxy_mode == 'Manual proxy configuration'` the `manual` family is enabled
|
|
|
|
**Keywords**
|
|
|
|
- We now know what a *property* is, we have seen in details the :term:`disabled` property
|
|
- We can target a variable's value in the `disabled` property's value,
|
|
we call it a variable based contextual disabled family
|
|
|