377 lines
13 KiB
ReStructuredText
377 lines
13 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
|
|
|
|
We have this `disabled: true` property assigned to the `manual` family.
|
|
|
|
.. 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 from the Rougail CLI output that the `manual` family is not taken into account by Rougail.
|
|
Let's first examine what this disabled property does.
|
|
|
|
.. 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
|
|
|
|
We can see that the Rougail CLI is warning us that the variables we are trying to assign values on are disabled.
|
|
That is to say, they are not taken into account at the :term:`configuration` level.
|
|
|
|
If we have a closer look at 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
|
|
|
|
Actually if the `Manual proxy configuration` is not selected, we don't need to set
|
|
these `address` and `port` variables, there is no point in setting them in
|
|
four out of our five use cases.
|
|
|
|
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 whole :term:`configuration`.
|
|
We shall fill and use in these variables in the `Manual proxy configuration` use case context only.
|
|
Otherwise, **we need to disable them when they are not necessary**.
|
|
|
|
In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it.
|
|
He will wonder : "oh, 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 variables one by one can be replaced by disabling a family
|
|
|
|
If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable
|
|
all the subfamilies and the variables in it.
|
|
|
|
Note that we've placed theses variables in the `http_proxy`
|
|
subfamily. We can then disable it or even the parent `manual` subfamily in order to
|
|
disable the `http_proxy` family and all the variables that are placed in it, because
|
|
the `manual` family variables shall be used only in the manual proxy use case context.
|
|
|
|
Notice the `disabled: true` parameter set in the `manual` family:
|
|
|
|
.. 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 is disabled here
|
|
|
|
..
|
|
---
|
|
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
|
|
|
|
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 could be usefull here 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 property according to the chosen use case context.
|
|
|
|
In rougail, we can set a property's value **depending on** the value of another variable. **It is conditioned by** another variable.
|
|
|
|
.. 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
|
|
|
|
Now the `disabled` property has some parameter defined. First, let's explaine the `variable` parameter.
|
|
This parameter specifies the target variable. The value of this target variable
|
|
will be used to dynamically enable or disable our `manual` family.
|
|
|
|
We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value.
|
|
The target variable is `_.proxy_mode`.
|
|
|
|
The `.` notation means the path of the family or subfamily you're currently in.
|
|
The `_.` notation means the parent path of the current family or subfamily path.
|
|
|
|
Regarding the `when_not` parameter, it means that if the target variable's value
|
|
is `Manual proxy configuration` then the `manual` **will not** be disabled (that is, it will be enabled).
|
|
|
|
Here 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
|
|
|
|
If the manual mode for the proxy is not selected, then the `manual` family is disabled.
|
|
On the other hand, if the manual proxy's configuration mode is selected,
|
|
then the `manual` family is re-activated (enabled).
|
|
|
|
Now we are going to select the ** manual mode**, that is the `Manual proxy configuration`
|
|
value for the `proxy_mode` variable, and things will become slightly different.
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The `proxy_mode`'s manual setting in the :file:`config/02/config.yaml` user datas file
|
|
|
|
..
|
|
---
|
|
proxy_mode: Manual proxy configuration
|
|
manual:
|
|
http_proxy:
|
|
address: http.proxy.net
|
|
port: 3128
|
|
use_for_https: false
|
|
|
|
.. note:: Remember that this activation/deactivation of the `manual` family
|
|
depends on the value of the `proxy_mode` variable. Here we have
|
|
chosen the `Manual proxy configuration` value.
|
|
|
|
.. rubric:: Explanation
|
|
|
|
Here the `disabled` property **depends on** the value of the `proxy_mode` variable.
|
|
It is the `variable` parameter that allows you to define the name of the target variable on which the `disabled` property depends.
|
|
|
|
Copy HTTP manual proxy to HTTPS manual proxy
|
|
---------------------------------------------
|
|
|
|
.. type-along:: For those who follow the tutorial with the help of the git repository
|
|
|
|
Now you need to checkout the `v1.1_042` version::
|
|
|
|
git switch --detach v1.1_042
|
|
|
|
|
|
We have split the definition of the `manual` familiy into two specific files:
|
|
|
|
.. raw:: html
|
|
:class: output
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html
|
|
|
|
Here is the new :file:`20-manual.yml` file:
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The :file:`firefox/20-manual.yml` structure file with the `https_proxy` family.
|
|
|
|
..
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
manual:
|
|
|
|
use_for_https: true # Also use this proxy for HTTPS
|
|
|
|
https_proxy: # HTTPS Proxy
|
|
|
|
address:
|
|
description: HTTPS address
|
|
type: domainname
|
|
params:
|
|
allow_ip: true
|
|
|
|
port:
|
|
description: HTTPS Port
|
|
type: port
|
|
default: 8080
|
|
|
|
This `https_proxy` family is identical to the `http_proxy` family except that it defines variables intended for the HTTPS protocol.
|
|
|
|
Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, its default value is `True`.
|
|
We want to offer the possibility of providing the same proxy configuration for the HTTP and the HTTPS requests.
|
|
|
|
A conditional hidden family
|
|
----------------------------
|
|
|
|
.. type-along:: For those who follow the tutorial with the help of the git repository
|
|
|
|
Now you need to checkout the `v1.1_043` version::
|
|
|
|
git switch --detach v1.1_043
|
|
|
|
|
|
|
|
|
|
.. keypoints:: Key points progress
|
|
|
|
**summary**
|
|
|
|
We have now the ability to build a contextual setting:
|
|
|
|
- if the `proxy_mode` variable's value is not `'Manual proxy configuration'` the `manual` family is disabled
|
|
- if the `proxy_mode` variable's value is `'Manual proxy configuration'` then 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
|
|
|