36 KiB
36 KiB
[tutorial v1.1_211] redefines the behavior to password mandatory if the user is defined
Screenshot
Clone and install
To test this tutorial, you need to download this repository and install Rougail:
git clone -b 1.1 https://forge.cloud.silique.fr/stove/rougail-tutorials.git
cd rougail-tutorials
python -m venv venv_rougail
. venv_rougail/bin/activate
pip install rougail-cli rougail-output-exporter rougail-output-doc rougail-user-data-yaml
Then switch to the tutorial page:
git switch --detach v1.1_211
Structure
.
├── firefox
│ ├── 00-proxy.yml
│ ├── 10-manual.yml
│ ├── 20-manual.yml
│ ├── 30-auto.yml
│ ├── 40-no_proxy.yml
│ ├── 50-prompt_authentication.yml
│ ├── 55-proxy_dns_socks5.yml
│ └── 60-dns_over_https.yml
├── foxyproxy
│ ├── 00-foxyproxy.yml
│ └── 10-redefine.yml
└── types
└── proxy
└── 00-type.yml
Contents of the foxyproxy/10-redefine.yml file
%YAML 1.2
---
version: 1.1
proxies:
username:
redefine: true
mandatory: false
password:
redefine: true
hidden:
jinja: |-
{{ not _.username }}
return_type: boolean
description: if username is empty
...
Let's generate the documentation```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -o doc
#### Firefox
> [!NOTE]
>
> This family is a namespace.\
> **Path**: firefox\
> `basic`
| Variable | Description |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.proxy_mode" name="firefox.proxy_mode">firefox.proxy_mode</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Configure Proxy Access to the Internet.<br/>**Choices**: <br/>• No proxy **← (default)**<br/>• Auto-detect proxy settings for this network<br/>• Use system proxy settings<br/>• Manual proxy configuration<br/>• Automatic proxy configuration URL |
##### Manual proxy configuration
> [!NOTE]
>
> **Path**: firefox.manual\
> `basic` *`disabled`*\
> **Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" hasn't the value "Manual proxy configuration".
###### HTTP Proxy
> [!NOTE]
>
> **Path**: firefox.manual.http_proxy\
> `basic`
| Variable | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.manual.http_proxy.address" name="firefox.manual.http_proxy.address">firefox.manual.http_proxy.address</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `basic` `mandatory` | Proxy address.<br/>**Validators**: <br/>• type domainname<br/>• the domain name can be an IP |
| **<a id="firefox.manual.http_proxy.port" name="firefox.manual.http_proxy.port">firefox.manual.http_proxy.port</a>**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy port.<br/>**Validators**: <br/>• well-known ports (1 to 1023) are allowed<br/>• registred ports (1024 to 49151) are allowed<br/>• private ports (greater than 49152) are allowed<br/>**Default**: 8080 |
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| **<a id="firefox.manual.use_for_https" name="firefox.manual.use_for_https">firefox.manual.use_for_https</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Also use this proxy for HTTPS.<br/>**Default**: true |
###### HTTPS Proxy
> [!NOTE]
>
> **Path**: firefox.manual.https_proxy\
> `standard` *`hidden`*\
> **Hidden**: when the variable "[Also use this proxy for HTTPS](#firefox.manual.use_for_https)" has the value "true".
| Variable | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.manual.https_proxy.address" name="firefox.manual.https_proxy.address">firefox.manual.https_proxy.address</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy address.<br/>**Validators**: <br/>• type domainname<br/>• the domain name can be an IP<br/>**Default**: the value of the variable "[Proxy address](#firefox.manual.http_proxy.address)". |
| **<a id="firefox.manual.https_proxy.port" name="firefox.manual.https_proxy.port">firefox.manual.https_proxy.port</a>**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy port.<br/>**Validators**: <br/>• well-known ports (1 to 1023) are allowed<br/>• registred ports (1024 to 49151) are allowed<br/>• private ports (greater than 49152) are allowed<br/>**Default**: the value of the variable "[Proxy port](#firefox.manual.http_proxy.port)". |
###### SOCKS Proxy
> [!NOTE]
>
> **Path**: firefox.manual.socks_proxy\
> `standard`
| Variable | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.manual.socks_proxy.address" name="firefox.manual.socks_proxy.address">firefox.manual.socks_proxy.address</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy address.<br/>**Validators**: <br/>• type domainname<br/>• the domain name can be an IP<br/>**Default**: the value of the variable "[Proxy address](#firefox.manual.http_proxy.address)". |
| **<a id="firefox.manual.socks_proxy.port" name="firefox.manual.socks_proxy.port">firefox.manual.socks_proxy.port</a>**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy port.<br/>**Validators**: <br/>• well-known ports (1 to 1023) are allowed<br/>• registred ports (1024 to 49151) are allowed<br/>• private ports (greater than 49152) are allowed<br/>**Default**: the value of the variable "[Proxy port](#firefox.manual.http_proxy.port)". |
| **<a id="firefox.manual.socks_proxy.version" name="firefox.manual.socks_proxy.version">firefox.manual.socks_proxy.version</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | SOCKS host version used by proxy.<br/>**Choices**: <br/>• v4<br/>• v5 **← (default)** |
| Variable | Description |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.auto" name="firefox.auto">firefox.auto</a>**<br/>[`web address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `basic` `mandatory` *`disabled`* | Automatic proxy configuration URL.<br/>**Validators**: <br/>• well-known ports (1 to 1023) are allowed<br/>• registred ports (1024 to 49151) are allowed<br/>• type domainname<br/>• the domain name can be a hostname<br/>**Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" hasn't the value "Automatic proxy configuration URL". |
| **<a id="firefox.no_proxy" name="firefox.no_proxy">firefox.no_proxy</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `standard` *`disabled`* `unique` | Address for which proxy will be desactivated.<br/>Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.<br/>**Validators**: <br/>• type domainname<br/>• the domain name can starts by a dot<br/>• the domain name can be a hostname<br/>• the domain name can be an IP<br/>• the domain name can be network in CIDR format<br/>**Examples**: <br/>• .mozilla.org<br/>• .net.nz<br/>• 192.168.1.0/24<br/>**Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" has the value "No proxy". |
| **<a id="firefox.prompt_authentication" name="firefox.prompt_authentication">firefox.prompt_authentication</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` *`disabled`* | Prompt for authentication if password is saved.<br/>**Default**: true<br/>**Disabled**: when the variable "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" has the value "No proxy". |
| **<a id="firefox.proxy_dns_socks5" name="firefox.proxy_dns_socks5">firefox.proxy_dns_socks5</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `advanced` `mandatory` *`disabled`* | Use proxy DNS when using SOCKS v5.<br/>**Default**: false<br/>**Disabled**: if "[Configure Proxy Access to the Internet](#firefox.proxy_mode)" is not "Manual proxy configuration"<br/>or "[SOCKS host version used by proxy](#firefox.manual.socks_proxy.version)" is "v4". |
##### DNS over HTTPS
> [!NOTE]
>
> **Path**: firefox.dns_over_https\
> `basic`
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="firefox.dns_over_https.enable_dns_over_https" name="firefox.dns_over_https.enable_dns_over_https">firefox.dns_over_https.enable_dns_over_https</a>**<br/>[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Enable DNS over HTTPS.<br/>**Default**: false |
| **<a id="firefox.dns_over_https.provider" name="firefox.dns_over_https.provider">firefox.dns_over_https.provider</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` *`disabled`* | Use Provider.<br/>**Choices**: <br/>• Cloudflare **← (default)**<br/>• NextDNS<br/>• Custom<br/>**Disabled**: when the variable "[Enable DNS over HTTPS](#firefox.dns_over_https.enable_dns_over_https)" has the value "false". |
| **<a id="firefox.dns_over_https.custom_dns_url" name="firefox.dns_over_https.custom_dns_url">firefox.dns_over_https.custom_dns_url</a>**<br/>[`web address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `basic` `mandatory` *`disabled`* | Custom DNS URL.<br/>**Validators**: <br/>• well-known ports (1 to 1023) are allowed<br/>• registred ports (1024 to 49151) are allowed<br/>• type domainname<br/>• the domain name can be a hostname<br/>• must starts with 'https://' only<br/>**Disabled**: if "[Use Provider](#firefox.dns_over_https.provider)" is not "Custom". |
#### FoxyProxy
> [!NOTE]
>
> This family is a namespace.\
> **Path**: foxyproxy\
> `basic`
##### Proxy configuration
> [!NOTE]
>
> This family contains lists of variable blocks.\
> **Path**: foxyproxy.proxies\
> `basic`
| Variable | Description |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **<a id="foxyproxy.proxies.title" name="foxyproxy.proxies.title">foxyproxy.proxies.title</a>**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `multiple` `standard` `unique` | Title or Description. |
| **<a id="foxyproxy.proxies.type" name="foxyproxy.proxies.type">foxyproxy.proxies.type</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` | Proxy Type.<br/>**Choices**: <br/>• HTTP<br/>• HTTPS/SSL<br/>• SOCKS4<br/>• SOCKS5<br/>• PAC URL<br/>• WPAD<br/>• System (use system settings)<br/>• Direct (no proxy) **← (default)** |
| **<a id="foxyproxy.proxies.color" name="foxyproxy.proxies.color">foxyproxy.proxies.color</a>**<br/>[`regexp`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `basic` `mandatory` `auto modified` | Color.<br/>**Validator**: text based with regular expressions "^#(?:[0-9a-f]{3}){1,2}$"<br/>**Default**: random color value. |
| **<a id="foxyproxy.proxies.address" name="foxyproxy.proxies.address">foxyproxy.proxies.address</a>**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` *`disabled`* | IP address, DNS name, server name.<br/>**Validators**: <br/>• type domainname<br/>• the domain name can be a hostname<br/>• the domain name can be an IP<br/>**Default**: copy HTTP address if proxy is not "Manual".<br/>**Disabled**: if type not in:<br/>- HTTP<br/>- HTTPS/SSL<br/>- SOCKS4<br/>- SOCKS5. |
| **<a id="foxyproxy.proxies.port" name="foxyproxy.proxies.port">foxyproxy.proxies.port</a>**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` *`disabled`* | Port.<br/>**Validators**: <br/>• well-known ports (1 to 1023) are allowed<br/>• registred ports (1024 to 49151) are allowed<br/>• private ports (greater than 49152) are allowed<br/>**Default**: copy HTTP port if proxy is not "Manual".<br/>**Disabled**: if type not in:<br/>- HTTP<br/>- HTTPS/SSL<br/>- SOCKS4<br/>- SOCKS5. |
| **<a id="foxyproxy.proxies.username" name="foxyproxy.proxies.username">foxyproxy.proxies.username</a>**<br/>[`UNIX user`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` *`disabled`* | Username.<br/>**Disabled**: if type not in:<br/>- HTTP<br/>- HTTPS/SSL<br/>- SOCKS4<br/>- SOCKS5. |
| **<a id="foxyproxy.proxies.password" name="foxyproxy.proxies.password">foxyproxy.proxies.password</a>**<br/>[`secret`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` *`hidden`* *`disabled`* | Password.<br/>**Hidden**: if username is empty.<br/>**Disabled**: if type not in:<br/>- HTTP<br/>- HTTPS/SSL<br/>- SOCKS4<br/>- SOCKS5. |
| **<a id="foxyproxy.proxies.url" name="foxyproxy.proxies.url">foxyproxy.proxies.url</a>**<br/>[`web address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `standard` `mandatory` *`disabled`* | URL.<br/>**Validators**: <br/>• well-known ports (1 to 1023) are allowed<br/>• registred ports (1024 to 49151) are allowed<br/>• type domainname<br/>• the domain name can be a hostname<br/>**Default**: copy HTTP address if proxy is "Auto".<br/>**Disabled**: if type is not in:<br/>- PAC URL<br/>- WPAD. |
***
### Let's generate the changelog```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -o doc --doc.contents changelog --doc.changelog.previous_json_file previous.yml
Modified variables
| Variable | Description |
|---|---|
foxyproxy.proxies.usernamemandatoryUNIX user standard disabled |
Username. Mandatory: Disabled: if type not in: - HTTP - HTTPS/SSL - SOCKS4 - SOCKS5. |
foxyproxy.proxies.passwordsecret standard hidden disabled |
Password. Hidden: if username is empty. Disabled: if type not in: - HTTP - HTTPS/SSL - SOCKS4 - SOCKS5. |
User datas### Example 1#### config/01/config.yml
---
Output```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml
> [!NOTE]
>
> **Caption:**
> - Variable
> - <span style="color: #B8860B">Default value</span>
Variables:
- :open_file_folder: firefox (Firefox)
- :notebook: proxy_mode (Configure Proxy Access to the Internet): <span style="color: #B8860B">No proxy</span>
- :open_file_folder: dns_over_https (DNS over HTTPS)
- :notebook: enable_dns_over_https (Enable DNS over HTTPS): <span style="color: #B8860B">false</span>
- :open_file_folder: foxyproxy (FoxyProxy)
- :open_file_folder: proxies (Proxy configuration): <span style="color: #B8860B">[]</span>
***
### Example 2#### config/02/config.yml
```yml
---
foxyproxy:
proxies:
- title: My company
type: HTTP
color: '#66cc66'
address: proxy.company.net
port: 8080
username: one_user
password: P4ssW0rD
- title: An other company
type: HTTP
address: proxy.company.net
port: 8080
Output```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/02/config.yml
> [!NOTE]
>
> **Caption:**
> - Variable
> - <span style="color: #A52A2A">Unmodifiable variable</span>
> - <span style="color: #B8860B">Default value</span>
> - <span style="color: #006400">Modified value</span>
> - (:hourglass_flowing_sand: Original default value)
Variables:
- :open_file_folder: firefox (Firefox)
- :notebook: proxy_mode (Configure Proxy Access to the Internet): <span style="color: #B8860B">No proxy</span>
- :open_file_folder: dns_over_https (DNS over HTTPS)
- :notebook: enable_dns_over_https (Enable DNS over HTTPS): <span style="color: #B8860B">false</span>
- :open_file_folder: foxyproxy (FoxyProxy)
- :open_file_folder: proxies (Proxy configuration)
- :open_file_folder: title (Title or Description)
- :notebook: title (Title or Description): <span style="color: #006400">My company</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: type (Proxy Type): <span style="color: #006400">HTTP</span> ← loaded from the YAML file "config/02/config.yml" (:hourglass_flowing_sand: Direct (no proxy))
- :notebook: color (Color): <span style="color: #006400">#66cc66</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: address (IP address, DNS name, server name): <span style="color: #006400">proxy.company.net</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: port (Port): <span style="color: #006400">8080</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: username (Username): <span style="color: #006400">one_user</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: password (Password): <span style="color: #006400">**********</span> ← loaded from the YAML file "config/02/config.yml"
- :open_file_folder: title (Title or Description)
- :notebook: title (Title or Description): <span style="color: #006400">An other company</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: type (Proxy Type): <span style="color: #006400">HTTP</span> ← loaded from the YAML file "config/02/config.yml" (:hourglass_flowing_sand: Direct (no proxy))
- :notebook: color (Color): <span style="color: #006400">#af28a0</span>
- :notebook: address (IP address, DNS name, server name): <span style="color: #006400">proxy.company.net</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: port (Port): <span style="color: #006400">8080</span> ← loaded from the YAML file "config/02/config.yml"
- :notebook: username (Username): <span style="color: #B8860B">null</span>
- :notebook: <span style="color: #A52A2A">password (Password)</span>: <span style="color: #B8860B">null</span>
***
### Example 3#### config/03/config.yml
```yml
---
foxyproxy:
proxies:
- title: My company
type: HTTP
color: '#66cc66'
address: proxy.company.net
port: 8080
password: P4ssW0rD
- title: An other company
type: HTTP
address: proxy.company.net
port: 8080
Output```shell
rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/03/config.yml
> [!WARNING]
>
> - foxyproxy (FoxyProxy)
> - proxies (Proxy configuration)
> - password (Password): :bell: <span style="color: #EFBF04">variable "password" (Password) at index "0" is hidden, it will be ignored when loading from the YAML file "config/03/config.yml"</span>
> [!NOTE]
>
> **Caption:**
> - Variable
> - <span style="color: #A52A2A">Unmodifiable variable</span>
> - <span style="color: #B8860B">Default value</span>
> - <span style="color: #006400">Modified value</span>
> - (:hourglass_flowing_sand: Original default value)
Variables:
- :open_file_folder: firefox (Firefox)
- :notebook: proxy_mode (Configure Proxy Access to the Internet): <span style="color: #B8860B">No proxy</span>
- :open_file_folder: dns_over_https (DNS over HTTPS)
- :notebook: enable_dns_over_https (Enable DNS over HTTPS): <span style="color: #B8860B">false</span>
- :open_file_folder: foxyproxy (FoxyProxy)
- :open_file_folder: proxies (Proxy configuration)
- :open_file_folder: title (Title or Description)
- :notebook: title (Title or Description): <span style="color: #006400">My company</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: type (Proxy Type): <span style="color: #006400">HTTP</span> ← loaded from the YAML file "config/03/config.yml" (:hourglass_flowing_sand: Direct (no proxy))
- :notebook: color (Color): <span style="color: #006400">#66cc66</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: address (IP address, DNS name, server name): <span style="color: #006400">proxy.company.net</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: port (Port): <span style="color: #006400">8080</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: username (Username): <span style="color: #B8860B">null</span>
- :notebook: <span style="color: #A52A2A">password (Password)</span>: <span style="color: #B8860B">null</span>
- :open_file_folder: title (Title or Description)
- :notebook: title (Title or Description): <span style="color: #006400">An other company</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: type (Proxy Type): <span style="color: #006400">HTTP</span> ← loaded from the YAML file "config/03/config.yml" (:hourglass_flowing_sand: Direct (no proxy))
- :notebook: color (Color): <span style="color: #006400">#97f2cc</span>
- :notebook: address (IP address, DNS name, server name): <span style="color: #006400">proxy.company.net</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: port (Port): <span style="color: #006400">8080</span> ← loaded from the YAML file "config/03/config.yml"
- :notebook: username (Username): <span style="color: #B8860B">null</span>
- :notebook: <span style="color: #A52A2A">password (Password)</span>: <span style="color: #B8860B">null</span>
***