682 lines
30 KiB
ReStructuredText
682 lines
30 KiB
ReStructuredText
Define access to variable or family
|
||
==========================================
|
||
|
||
.. 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'll also learn the difference
|
||
between disabling and hiding families or variables.
|
||
Then we'll see the same thing for the `hidden` property.
|
||
|
||
We will:
|
||
|
||
- create a `disabled` family
|
||
- use a new family or variable's property: the `hidden` property
|
||
|
||
Disabling and hiding are two families or variables properties.
|
||
|
||
.. 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_050 <src/tag/v1.1_050>` to :tutorial:`v1.1_053 <src/tag/v1.1_053>`
|
||
in the repository.
|
||
|
||
::
|
||
|
||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||
git switch --detach v1.1_050
|
||
|
||
.. type-along:: What a property is
|
||
|
||
Let's begin with defining what a property is:
|
||
|
||
.. 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_050/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
|
||
|
||
Notice that we have this `disabled: true` property assigned to the `manual` family.
|
||
Let's launch the Rougail CLI on this structure file (whith an empty user data file):
|
||
|
||
.. raw:: html
|
||
:class: terminal
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/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_050/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.
|
||
So what does this disabled property exactly?
|
||
|
||
.. 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, as with any property, if a family has been disabled, all variables and sub-families that it contains are disabled.
|
||
|
||
And if we try to assign values to variables that have been disabled, here is what happens:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/02/config.yml
|
||
:language: yaml
|
||
:caption: In this :file:`config/02/config.yml` user data file, we assign values to variables that have been disabled
|
||
|
||
If we launch the Rougail CLI:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_050/config/02/cmd_unknown.txt
|
||
:class: terminal
|
||
|
||
..
|
||
rougail -m firefox/ -u yaml -yf config/02/config.yml --cli.unknown_user_data_error
|
||
|
||
It outputs:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_050/config/02/output_unknown.html
|
||
:class: output
|
||
|
||
..
|
||
<pre><span style="font-weight: bold; color: #ff0000">🛑 Caution</span>
|
||
<span style="color: #ff0000">┗━━ </span>manual (Manual proxy configuration)
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┣━━ </span>http_proxy (HTTP Proxy)
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">┣━━ </span>address (HTTP address): <span style="color: #ff0000">🛑 family "manual" (Manual proxy </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">configuration) has property disabled, so cannot access to "address" </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">(HTTP address), it has been loading from the YAML file </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">"config/02/config.yml"</span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000">┗━━ </span>port (HTTP Port): <span style="color: #ff0000">🛑 family "manual" (Manual proxy configuration) </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000"> </span><span style="color: #ff0000">has property disabled, so cannot access to "port" (HTTP Port), it </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┃ </span><span style="color: #ff0000"> </span><span style="color: #ff0000">has been loading from the YAML file "config/02/config.yml"</span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┗━━ </span>use_for_https (Also use this proxy for HTTPS): <span style="color: #ff0000">🛑 family "manual" </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000">(Manual proxy configuration) has property disabled, so cannot access to </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000">"use_for_https" (Also use this proxy for HTTPS), it has been loading </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000">from the YAML file "config/02/config.yml"</span>
|
||
</pre>
|
||
|
||
|
||
We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which are disabled.
|
||
Because it is not logical. We are trying to assign values to variables that are not taken into account in the :term:`configuration`.
|
||
|
||
The point is 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 used**.
|
||
|
||
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.
|
||
|
||
.. type-along:: The `disabling` property is usefull in our use case
|
||
|
||
Let's look again 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.
|
||
|
||
.. important:: We need to **disable** variables or families that are not used
|
||
in a given usage context.
|
||
|
||
A disabled family
|
||
------------------
|
||
|
||
Disabling variables one by one can be replaced by disabling a whole 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_050/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_051` version::
|
||
|
||
git switch --detach v1.1_051
|
||
|
||
What could be usefull here is a *dynamically* disable or enable 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.
|
||
**The property's value is conditioned by** another variable.
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/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`.
|
||
|
||
.. note:: The `_.` notation means the current path of the family you're currently in.
|
||
|
||
In the python quasi algorithmic notation we could say that:
|
||
|
||
.. code-block:: python
|
||
|
||
_.proxy_mode == proxy_mode
|
||
|
||
This is true only because in our use case `proxy_mode` is located on the root path.
|
||
|
||
Now regarding the `when_not` parameter, this means that if the target variable's value
|
||
is `Manual proxy configuration` then the `manual` familiy **will not** be disabled
|
||
(that is, it will be **enabled**).
|
||
|
||
Regarding as the default value use case, the `proxy_mode`'s variable is `No proxy` by default.
|
||
The `manual` familiy is then **disabled by default**.
|
||
|
||
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_051/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_051/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 we are going to choose the **manual mode**, that is the `Manual proxy configuration`
|
||
value for the `proxy_mode` variable, and things will become slightly different.
|
||
|
||
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 enabled**:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/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
|
||
|
||
Let's launch the Rougail CLI to verify this:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/cmd_ro.txt
|
||
:class: terminal
|
||
|
||
..
|
||
rougail -m firefox/ -u yaml -yf config/02/config.yml
|
||
|
||
It outputs:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/output_ro.html
|
||
:class: output
|
||
|
||
..
|
||
<pre>╭────────────── Caption ───────────────╮
|
||
│ Variable <span style="color: #00aa00">Modified value</span> │
|
||
│ (⏳ Original default value) │
|
||
╰──────────────────────────────────────╯
|
||
Variables:
|
||
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
|
||
<span style="color: #5c5cff">┃ </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/02/config.yml" (⏳ No
|
||
<span style="color: #5c5cff">┃ </span>proxy)
|
||
<span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┃ </span>file "config/02/config.yml"
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff"> </span>"config/02/config.yml" (⏳ 8080)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span>the YAML file "config/02/config.yml" (⏳ true)
|
||
</pre>
|
||
|
||
.. 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.
|
||
|
||
Please 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, so the `address` and `port` variables appear.
|
||
|
||
A 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_052` version::
|
||
|
||
git switch --detach v1.1_052
|
||
|
||
Let's introduce a new property here:
|
||
|
||
.. glossary::
|
||
|
||
hidden
|
||
|
||
A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`.
|
||
Anyway, these variables can be used if the context evolves.
|
||
|
||
This is the main difference between the `hidden` and the `disabled` properties:
|
||
|
||
- with the `disabled` property, the variables are *deactivated*
|
||
- with the `hidden` property, the variables are just not seen when loading the user data.
|
||
|
||
.. questions:: Question: shall we use the `disabled` property here?
|
||
|
||
Is it relevant to use the :term:`disabled property <disabled>` here?
|
||
|
||
**answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case,
|
||
we simply have to point their values in one direction or another depending on this or that context,
|
||
that's why it is absolutely not a question of disabling them. The `manual.https_proxy.address`
|
||
and the `manual.http_proxy.port` variables shall not be disabled in the manual mode.
|
||
|
||
Now we can set a `hidden` property to the `https_proxy` family:
|
||
|
||
Here is our new :file:`20-manual.yml` structure file:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/firefox/20-manual.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
|
||
|
||
..
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
manual:
|
||
|
||
use_for_https: true # Also use this proxy for HTTPS
|
||
|
||
https_proxy:
|
||
description: HTTPS Proxy
|
||
hidden: true
|
||
|
||
address:
|
||
description: HTTPS address
|
||
default:
|
||
variable: __.http_proxy.address
|
||
|
||
port:
|
||
description: HTTPS Port
|
||
default:
|
||
variable: __.http_proxy.port
|
||
...
|
||
|
||
We have added two other variables for the HTTPS use only:
|
||
|
||
.. confval:: https_proxy.address
|
||
:type: `domainname`
|
||
|
||
This is an address setting for the manual HTTPS configuration
|
||
|
||
.. confval:: https_proxy.port
|
||
:type: `port`
|
||
|
||
This is a port setting for the manual HTTPS configuration
|
||
|
||
We have now a `hidden` property assigned to the `https_proxy` family, which is
|
||
hiding these two variables.
|
||
|
||
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_053` version::
|
||
|
||
git switch --detach v1.1_053
|
||
|
||
Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen,
|
||
let's have a look at our use case again:
|
||
|
||
.. image:: images/firefox_manual_https.png
|
||
|
||
Let's have a look at the HTPPS configuration corresponding structure file:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/firefox/20-manual.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: the :file:`firefox/20-manual.yml` structure file
|
||
|
||
..
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
manual:
|
||
|
||
use_for_https: true # Also use this proxy for HTTPS
|
||
|
||
https_proxy:
|
||
description: HTTPS Proxy
|
||
hidden:
|
||
variable: _.use_for_https
|
||
|
||
address:
|
||
description: HTTPS address
|
||
default:
|
||
variable: __.http_proxy.address
|
||
|
||
port:
|
||
description: HTTPS Port
|
||
default:
|
||
variable: __.http_proxy.port
|
||
...
|
||
|
||
Let's introduce a new Rougail concept here:
|
||
|
||
.. glossary::
|
||
|
||
context
|
||
|
||
A :term:`configuration` is highly statefull and can change at any moment.
|
||
Sometimes somes minor changes in the :term:`user data <user data>` may involve chain reactions
|
||
in the whole :term:`configuration`.
|
||
The **context** is the state of the user data at one moment, the set of the values of the variables
|
||
at a given moment.
|
||
|
||
This term refers in Rougail to the ability of a system to handle
|
||
the *statefull* state of a configuration.
|
||
It expresses the transition between one situation to another situation,
|
||
that is, the deeply **statefull** aspects of a data set.
|
||
|
||
.. type-along:: A new variable which has the `boolean` type
|
||
|
||
The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
|
||
is to add this `use_for_https` variable in our structure file. This boolean variable can reproduce this binary choice option.
|
||
|
||
- if the use of the proxy variables for https are the same of the proxy variables for http,
|
||
that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK.
|
||
- if the use of the proxy variables for https **are not** the same of the proxy variables for http,
|
||
we would like to set their default values to the http proxy variables values.
|
||
|
||
Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
|
||
Well, it depends on the :term:`context`.
|
||
|
||
We have added a new variable, named `use_for_https` here:
|
||
|
||
.. confval:: use_for_https
|
||
:type: `boolean`
|
||
:default: `true`
|
||
|
||
This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS
|
||
|
||
The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has
|
||
a `variable` target parameter that points to it: `variable: _.use_for_https`.
|
||
|
||
.. prerequisites:: Reminder
|
||
|
||
The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the same
|
||
family.
|
||
|
||
.. questions:: Question: how does it work?
|
||
|
||
How will this variable drive the reuse of HTTP data to HTTPS data?
|
||
|
||
With this :confval:`use_for_https` boolean variable, there are two possibilities, and only two:
|
||
|
||
- The http proxy's configuration will be reused for the https proxy's configuration
|
||
- The http proxy's will not be reused for the https proxy's configuration
|
||
|
||
Here is an example with different user values for handling HTTP and HTTPS:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/config.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false
|
||
|
||
..
|
||
---
|
||
proxy_mode: Manual proxy configuration
|
||
manual:
|
||
http_proxy:
|
||
address: http.proxy.net
|
||
port: 3128
|
||
use_for_https: false
|
||
https_proxy:
|
||
address: https.proxy.net
|
||
|
||
If we launch the Rougail CLI:
|
||
|
||
.. raw:: html
|
||
:class: terminal
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/cmd_ro.txt
|
||
|
||
..
|
||
rougail -m firefox/ -u yaml -yf config/01/config.yml
|
||
|
||
We have this output:
|
||
|
||
.. raw:: html
|
||
:class: output
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/output_ro.html
|
||
|
||
..
|
||
<pre>╭────────────── Caption ───────────────╮
|
||
│ Variable <span style="color: #ffd700">Default value</span> │
|
||
│ <span style="color: #00aa00">Modified value</span> │
|
||
│ (⏳ Original default value) │
|
||
╰──────────────────────────────────────╯
|
||
Variables:
|
||
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
|
||
<span style="color: #5c5cff">┃ </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/01/config.yml" (⏳ No
|
||
<span style="color: #5c5cff">┃ </span>proxy)
|
||
<span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┃ </span>file "config/01/config.yml"
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff"> </span>"config/01/config.yml" (⏳ 8080)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span>the YAML file "config/01/config.yml" (⏳ true)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📂 https_proxy (HTTPS Proxy)
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTPS address): <span style="color: #00aa00">https.proxy.net</span> ◀ loaded from the YAML
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span>file "config/01/config.yml"
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTPS Port): <span style="color: #ffd700">8080</span>
|
||
</pre>
|
||
|
||
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 an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols.
|
||
|
||
Here is an example with identical HTTP and HTTPS proxy configuration:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/config.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true
|
||
|
||
..
|
||
---
|
||
proxy_mode: Manual proxy configuration
|
||
manual:
|
||
http_proxy:
|
||
address: http.proxy.net
|
||
port: 3128
|
||
use_for_https: true
|
||
|
||
Let's launch the Rougail CLI:
|
||
|
||
.. raw:: html
|
||
:class: terminal
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/cmd_ro.txt
|
||
|
||
..
|
||
rougail -m firefox/ -u yaml -yf config/02/config.yml
|
||
|
||
We have this output:
|
||
|
||
.. raw:: html
|
||
:class: output
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/output_ro.html
|
||
|
||
..
|
||
<pre><span style="font-weight: bold; color: #ff0000">🛑 Caution</span>
|
||
<span style="color: #ff0000">┗━━ </span>manual (Manual proxy configuration)
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000">┗━━ </span>https_proxy (HTTPS Proxy)
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000">┗━━ </span>address (HTTPS address): <span style="color: #ff0000">🛑 mandatory variable but is inaccessible </span>
|
||
<span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000">and has no value</span>
|
||
</pre>
|
||
|
||
Which is logical, HTTPS proxy variables have no values set yet.
|
||
We are going to see how to point HTTPS variables to HTTP variables.
|
||
|
||
.. keypoints:: Key points progress
|
||
|
||
**summary**
|
||
|
||
We have now the ability to build *contextual settings*:
|
||
|
||
- 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
|
||
- if the `use_for_https` variable's value is `true`, the HTTP configuration will be reused in the HTTPS situation
|
||
and the `https_proxy` familiy will be hidden
|
||
- if the `manual.https_proxy.address` has no value set, the defaut value is the same as the `manual.http_proxy.address`'s value
|
||
(same behavior with the HTTP port and the HTTPS port variable)
|
||
|
||
And yes, we did it. We have arrived at the end of the proxy's manual configuration's section.
|
||
|
||
**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,
|
||
- The :term:`hidden` property can be set to a family,
|
||
- The fact that a property can be set dynamically,
|
||
- The conditional dependency of a `hidden` property can depends on a `boolean` variable,
|
||
- We know what a calculated default value is.
|
||
|