• Summary
• [tutorial v1.1_114] xxx (diff)

[tutorial v1.1_120)] xxx

View the diff

Read the documentation

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_120

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
│   └── empty.yml
└── foxyproxy
    ├── 00-foxyproxy.yml
    └── 10-redefine.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: |-
        {% if not _.username %}
          no username defined
        {% endif %}        
      description: if username is not defined
...

Let's generate the documentation

rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --modes_level basic standard advanced -o doc

Variables for "Firefox"

firefox

basic

Variable	Description
firefox.proxy_mode choice standard mandatory	Configure Proxy Access to the Internet. Choices: - No proxy ← (default) - Auto-detect proxy settings for this network - Use system proxy settings - Manual proxy configuration - Automatic proxy configuration URL

Manual proxy configuration

firefox.manual

basic disabled

Disabled: when the variable "firefox.proxy_mode" hasn't the value "Manual proxy configuration"

HTTP Proxy

firefox.manual.http_proxy

basic

Variable	Description
firefox.manual.http_proxy.address domainname basic mandatory	HTTP address. Validator: the domain name can be an IP
firefox.manual.http_proxy.port port standard mandatory	HTTP Port. Validators: - well-known ports (1 to 1023) are allowed - registred ports (1024 to 49151) are allowed - private ports (greater than 49152) are allowed Default: 8080

Variable	Description
firefox.manual.use_for_https boolean standard mandatory	Also use this proxy for HTTPS. Default: true

HTTPS Proxy or SOCKS Proxy

This family builds families dynamically

firefox.manual.https_proxy
firefox.manual.socks_proxy

standard hidden

Hidden: in HTTPS case if "_.use_for_https" is set to "true"

Identifiers:
- HTTPS
- SOCKS

Variable	Description
firefox.manual.https_proxy.address firefox.manual.socks_proxy.address domainname standard mandatory	HTTPS or SOCKS address. Validator: the domain name can be an IP Default: the value of the variable "firefox.manual.http_proxy.address"
firefox.manual.https_proxy.port firefox.manual.socks_proxy.port port standard mandatory	HTTPS or SOCKS port. Validators: - well-known ports (1 to 1023) are allowed - registred ports (1024 to 49151) are allowed - private ports (greater than 49152) are allowed Default: the value of the variable "firefox.manual.http_proxy.port"
firefox.manual.https_proxy.version firefox.manual.socks_proxy.version choice standard mandatory disabled	SOCKS host version used by proxy. Choices: - v4 - v5 ← (default) Disabled: when the identifier is "HTTPS"

Variable	Description
firefox.auto web_address basic mandatory disabled	Automatic proxy configuration URL. Validator: the domain name in web address can be only a hostname Disabled: when the variable "firefox.proxy_mode" hasn't the value "Automatic proxy configuration URL"
firefox.no_proxy domainname standard disabled unique multiple	Address for which proxy will be desactivated. Connections to localhost, 127.0.0.1/8 and ::1 are never proxied. Validators: - the domain name can starts by a dot - the domain name can be a hostname - the domain name can be an IP - the domain name can be network in CIDR format Examples: - .mozilla.org - .net.nz - 192.168.1.0/24 Disabled: when the variable "firefox.proxy_mode" has the value "No proxy"
firefox.prompt_authentication boolean standard mandatory disabled	Prompt for authentication if password is saved. Default: true Disabled: when the variable "firefox.proxy_mode" has the value "No proxy"
firefox.proxy_dns_socks5 boolean advanced mandatory disabled	Use proxy DNS when using SOCKS v5. Default: false Disabled: if "firefox.proxy_mode" is not "Manual proxy configuration"
or "firefox.manual.socks_proxy.version" is "v4"

DNS over HTTPS

firefox.dns_over_https

basic

Variable	Description
firefox.dns_over_https.enable_dns_over_https boolean standard mandatory	Enable DNS over HTTPS. Default: false
firefox.dns_over_https.provider choice standard mandatory disabled	Use Provider. Choices: - Cloudflare ← (default) - NextDNS - Custom Disabled: when the variable "firefox.dns_over_https.enable_dns_over_https" has the value "false"
firefox.dns_over_https.custom_dns_url web_address basic mandatory disabled	Custom DNS URL. Validators: - the domain name in web address can be only a hostname - must starts with 'https://' only Disabled: if "_.provider" is not "Custom"

Variables for "FoxyProxy"

foxyproxy

basic

Proxy configuration

This family contains lists of variable blocks

foxyproxy.proxies

basic

Variable	Description
foxyproxy.proxies.title string standard unique multiple	Title or Description.
foxyproxy.proxies.type choice standard mandatory	Proxy Type. Choices: - HTTP - HTTPS/SSL - SOCKS4 - SOCKS5 - PAC URL - WPAD - System (use system settings) - Direct (no proxy) ← (default)
foxyproxy.proxies.color regexp basic mandatory auto modified	Color. Validator: text based with regular expressions "^#(?:[0-9a-f]{3}){1,2}$" Default: random color value
foxyproxy.proxies.address domainname standard mandatory disabled	IP address, DNS name, server name. Validators: - the domain name can be a hostname - the domain name can be an IP Default: copy HTTP address if proxy is not "Manual" Disabled: if type not in:

• HTTP
• HTTPS/SSL
• SOCKS4
• SOCKS5 | | foxyproxy.proxies.port
  port standard mandatory disabled | Port.
  Validators:
  - well-known ports (1 to 1023) are allowed
  - registred ports (1024 to 49151) are allowed
  - private ports (greater than 49152) are allowed
  Default: copy HTTP port if proxy is not "Manual"
  Disabled: if type not in:
• HTTP
• HTTPS/SSL
• SOCKS4
• SOCKS5 | | foxyproxy.proxies.username
  unix_user standard disabled | Username.
  Disabled: if type not in:
• HTTP
• HTTPS/SSL
• SOCKS4
• SOCKS5 | | foxyproxy.proxies.password
  secret standard hidden disabled | Password.
  Hidden: if username is not defined
  Disabled: if type not in:
• HTTP
• HTTPS/SSL
• SOCKS4
• SOCKS5 | | foxyproxy.proxies.url
  web_address standard mandatory disabled | URL.
  Validator: the domain name in web address can be only a hostname
  Default: copy HTTP address if proxy is "Auto"
  Disabled: if type is not in:
• PAC URL
• WPAD |

Let's generate the changelog

rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --modes_level basic standard advanced -o doc --doc.contents changelog

Modified variables

Variable	Description
foxyproxy.proxies.color regexp basic mandatory auto modified	Color. Validator: text based with regular expressions "^#(?:[0-9a-f]{3}){1,2}$" Default: random color value
foxyproxy.proxies.username mandatory unix_user standard disabled	Username. Mandatory: if a password is set Disabled: if type not in:

• HTTP
• HTTPS/SSL
• SOCKS4
• SOCKS5 | | foxyproxy.proxies.password
  secret standard hidden disabled | Password.
  Hidden: if username is not defined
  Disabled: if type not in:
• HTTP
• HTTPS/SSL
• SOCKS4
• SOCKS5 |