Table of Contents

• Summary
• Description
• Structure
• firefox/00-proxy.yml
• firefox/10-manual.yml
• firefox/20-manual.yml
• firefox/30-auto.yml
• firefox/40-no_proxy.yml
• firefox/50-prompt_authentication.yml
• firefox/55-proxy_dns_socks5.yml
• firefox/60-dns_over_https.yml
• foxyproxy/00-foxyproxy.yml
• Generated documentation
• Variables for "firefox"
• Manual proxy configuration
• HTTP Proxy
• "HTTPS Proxy" or "SOCKS Proxy"
• DNS over HTTPS
• Variables for "foxyproxy"
• Proxy configuration
• User data
• Example 1
• config/01/config.yaml
• Output
• Example 2
• config/02/config.yaml
• Output
• Example 3
• config/03/config.yaml
• Output

Summary

• [tutorial 001] An empty file (diff)
• [tutorial 002] A first variable (diff)
• [tutorial 003] A first variable (diff)
• [tutorial 004] The variable description (diff)
• [tutorial 005] A default value (diff)
• [tutorial 006] A variable with type choice (diff)
• [tutorial 007] Choice type is optional (diff)
• [tutorial 010] A family (diff)
• [tutorial 011] Conditional desactived family (diff)
• [tutorial 012] Conditional desactived family (diff)
• [tutorial 013] A sub family (diff)
• [tutorial 014] Family in "shorthand" mode (diff)
• [tutorial 015] Family in "shorthand" mode (diff)
• [tutorial 016] Family in "shorthand" mode (diff)
• [tutorial 017] Family in "shorthand" mode (diff)
• [tutorial 018] Family in "shorthand" mode (diff)
• [tutorial 020] A boolean variable (diff)
• [tutorial 021] Bases type is optional if default value (diff)
• [tutorial 022] A variable in "shorthand" mode (diff)
• [tutorial 023] Conditional hidden family and calculated default value (diff)
• [tutorial 024] Conditional hidden family and calculated default value (diff)
• [tutorial 025] Conditional hidden family and calculated default value (diff)
• [tutorial 026] A dynamic family (diff)
• [tutorial 027] A dynamic family (diff)
• [tutorial 028] Description of Jinja calculation (diff)
• [tutorial 029] Description of Jinja calculation (diff)
• [tutorial 030] A conditional disabled variable (diff)
• [tutorial 040] A conditional disabled variable (diff)
• [tutorial 041] A variable multi (diff)
• [tutorial 042] A non mandatory variable (diff)
• [tutorial 043] Examples (diff)
• [tutorial 044] Help (diff)
• [tutorial 050] A variable in avanced mode (diff)
• [tutorial 060] A boolean variable (diff)
• [tutorial 061] A choice variable (diff)
• [tutorial 062] A variable with custom validation (diff)
• [tutorial 100] xxx (diff)
• [tutorial 101] xxx (diff)
• [tutorial 102] xxx (diff)

Description

xxx

Structure

firefox/00-proxy.yml

---
proxy_mode:
  description: Configure Proxy Access to the Internet
  choices:
    - No proxy
    - Auto-detect proxy settings for this network
    - Use system proxy settings
    - Manual proxy configuration
    - Automatic proxy configuration URL
  default: No proxy

firefox/10-manual.yml

---
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

firefox/20-manual.yml

---
manual:

  use_for_https: true  # Also use this proxy for HTTPS

  "{{ suffix }}_proxy":
    description: "{{ suffix }} Proxy"
    dynamic:
      - HTTPS
      - SOCKS
    hidden:
      jinja: |
        {% if suffix == 'HTTPS' and _.use_for_https %}
        HTTPS is same has HTTP
        {% endif %}        
      params:
        suffix:
          type: suffix
      description: |
        in HTTPS case if "manual.use_for_https" is set to True        

    address:
      description: "{{ suffix }} address"
      default:
        variable: __.http_proxy.address

    port:
      description: "{{ suffix }} port"
      default:
        variable: __.http_proxy.port

    version:
      description: SOCKS host version used by proxy
      choices:
        - v4
        - v5
      default: v5
      disabled:
        type: suffix
        when: 'HTTPS'

firefox/30-auto.yml

---
auto:
  description: Automatic proxy configuration URL
  type: web_address
  disabled:
    variable: _.proxy_mode
    when_not: Automatic proxy configuration URL

firefox/40-no_proxy.yml

---
no_proxy:
  description: Address for which proxy will be desactivated
  type: "domainname"
  params:
    allow_ip: true
    allow_cidr_network: true
    allow_without_dot: true
    allow_startswith_dot: true
  multi: true
  mandatory: false
  disabled:
    variable: _.proxy_mode
    when: No proxy
  examples:
    - .mozilla.org
    - .net.nz
    - 192.168.1.0/24
  help: Connections to localhost, 127.0.0.1/8 and ::1 are never proxied

firefox/50-prompt_authentication.yml

---
prompt_authentication:
  description: Prompt for authentication if password is saved
  default: true
  disabled:
    variable: _.proxy_mode
    when: No proxy

firefox/55-proxy_dns_socks5.yml

---
proxy_dns_socks5:
  description: Use proxy DNS when using SOCKS v5
  default: false
  mode: advanced
  disabled:
    jinja: |
      {% if socks_version is not defined %}
      the proxy mode is not manual
      {% elif socks_version == 'v4' %}
      socks version is v4
      {% endif %}      
    params:
      socks_version:
        variable: _.manual.socks_proxy.version
        propertyerror: false
    description: |
      if "firefox.proxy_mode" is not "Manual proxy configuration" or "firefox.manual.socks_proxy.version" is "v4"      

firefox/60-dns_over_https.yml

---
dns_over_https:  # DNS over HTTPS

  enable_dns_over_https: false  # Enable DNS over HTTPS

  provider:
    description: Use Provider
    choices:
      - Cloudflare
      - NextDNS
      - Custom
    default: Cloudflare
    disabled:
      variable: _.enable_dns_over_https
      when: false

  custom_dns_url:
    description: Custom DNS URL
    type: web_address
    disabled:
      jinja: |
        {% if provider is not defined or provider != 'Custom' %}
        provider is not custom
        {% endif %}        
      params:
        provider:
          variable: _.provider
          propertyerror: false
      description: if "firefox.dns_over_https.provider" is not "Custom"
    validators:
      - jinja: |
          {% if _.custom_dns_url.startswith('http://') %}
          only https is allowed
          {% endif %}          
        description: must starts with 'https://' only

foxyproxy/00-foxyproxy.yml

---
proxies:
  description: Proxy configuration
  type: leadership

  title:
    description: Title or Description
    mandatory: false

  color:
    description: Color
    regexp: "^#(?:[0-9a-f]{3}){1,2}$"
    auto_save: true
    default:
      jinja: |
        #
        {%- for i in range(6) -%}
        {{- '0123456789abcdef' | random -}}
        {%- endfor -%}        
      description: random color value

Generated documentation

foo@bar:~$ rougail -v 1.1 -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ -o doc -do github

Variables for "firefox"

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

basic disabled

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

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. 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"

standard hidden

Hidden: in HTTPS case if "manual.use_for_https" is set to True.

This family builds families dynamically.

Suffixes:
- HTTPS
- SOCKS

Variable	Description
firefox.manual.https_proxy.address or firefox.manual.socks_proxy.address domainname standard mandatory	"HTTPS address" 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 or firefox.manual.socks_proxy.port port standard mandatory	"HTTPS port" or "SOCKS port". Default: the value of the variable "firefox.manual.http_proxy.port".
firefox.manual.https_proxy.version or firefox.manual.socks_proxy.version choice standard mandatory disabled	SOCKS host version used by proxy. Choices: - v4 - v5 ← (default) Disabled: when the suffix is "HTTPS".

Variable	Description
firefox.auto web_address basic mandatory disabled	Automatic proxy configuration URL. 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".

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. Validator: must starts with 'https://' only. Disabled: if "firefox.dns_over_https.provider" is not "Custom".

Variables for "foxyproxy"

Proxy configuration

basic

This family contains lists of variable blocks.

Variable	Description
foxyproxy.proxies.title string standard unique multiple	Title or Description.
foxyproxy.proxies.color regexp basic mandatory auto modified	Color. Default: random color value.

User data

Example 1

config/01/config.yaml

---

Output

foo@bar:~$ rougail -v 1.1 -m firefox -s Firefox -xn FoxyProxy -xd 0 foxyproxy -u file -ff config/01/config.yaml

╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           Default value            │
│ Undocumented variable              Modified value           │
│ Undocumented but modified variable (Original default value) │
│ Unmodifiable variable                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
┣━━ 📂 firefox
┃   ┣━━ 📓 proxy_mode: No proxy
┃   ┗━━ 📂 dns_over_https
┃       ┗━━ 📓 enable_dns_over_https: False
┗━━ 📂 foxyproxy
    ┗━━ 📂 proxies

Example 2

config/02/config.yaml

---
foxyproxy:
  proxies:
    - title: My company
      color: '#66cc66'
      type: HTTP
      address: proxy.company.net

Output

foo@bar:~$ rougail -v 1.1 -m firefox -s Firefox -xn FoxyProxy -xd 0 foxyproxy -u file -ff config/02/config.yaml

🛑 ERRORS
┣━━ unknown option "type" in optiondescription "foxyproxy.proxies (Proxy configuration)"
┗━━ unknown option "address" in optiondescription "foxyproxy.proxies (Proxy configuration)"
╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           Default value            │
│ Undocumented variable              Modified value           │
│ Undocumented but modified variable (Original default value) │
│ Unmodifiable variable                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
┣━━ 📂 firefox
┃   ┣━━ 📓 proxy_mode: No proxy
┃   ┗━━ 📂 dns_over_https
┃       ┗━━ 📓 enable_dns_over_https: False
┗━━ 📂 foxyproxy
    ┗━━ 📂 proxies
        ┗━━ 📂 title
            ┣━━ 📓 title: My company
            ┗━━ 📓 color: #66cc66

Example 3

config/03/config.yaml

---
firefox:
  proxy_mode: Manual proxy configuration
  manual:
    http_proxy:
      address: http.proxy.net
foxyproxy:
  proxies:
    - title: My company
      color: '#66cc66'
      type: HTTP
    - title: An other company
      color: '#cc66cc'
      type: SOCKS5
      username: my_user
      password: my_password
    - title: WPAD
      color: '#1166cc'
      type: WPAD
      url: http://wpad.proxy.net/wpad.dat

Output

foo@bar:~$ rougail -v 1.1 -m firefox -s Firefox -xn FoxyProxy -xd 0 foxyproxy -u file -ff config/03/config.yaml

🛑 ERRORS
┣━━ unknown option "type" in optiondescription "foxyproxy.proxies (Proxy configuration)"
┣━━ unknown option "type" in optiondescription "foxyproxy.proxies (Proxy configuration)"
┣━━ unknown option "username" in optiondescription "foxyproxy.proxies (Proxy configuration)"
┣━━ unknown option "password" in optiondescription "foxyproxy.proxies (Proxy configuration)"
┣━━ unknown option "type" in optiondescription "foxyproxy.proxies (Proxy configuration)"
┗━━ unknown option "url" in optiondescription "foxyproxy.proxies (Proxy configuration)"
╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           Default value            │
│ Undocumented variable              Modified value           │
│ Undocumented but modified variable (Original default value) │
│ Unmodifiable variable                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
┣━━ 📂 firefox
┃   ┣━━ 📓 proxy_mode: Manual proxy configuration (No proxy)
┃   ┣━━ 📂 manual
┃   ┃   ┣━━ 📂 http_proxy
┃   ┃   ┃   ┣━━ 📓 address: http.proxy.net
┃   ┃   ┃   ┗━━ 📓 port: 8080
┃   ┃   ┣━━ 📓 use_for_https: True
┃   ┃   ┣━━ 📂 https_proxy
┃   ┃   ┃   ┣━━ 📓 address: http.proxy.net
┃   ┃   ┃   ┗━━ 📓 port: 8080
┃   ┃   ┗━━ 📂 socks_proxy
┃   ┃       ┣━━ 📓 address: http.proxy.net
┃   ┃       ┣━━ 📓 port: 8080
┃   ┃       ┗━━ 📓 version: v5
┃   ┣━━ 📓 no_proxy :
┃   ┣━━ 📓 prompt_authentication: True
┃   ┣━━ 📓 proxy_dns_socks5: False
┃   ┗━━ 📂 dns_over_https
┃       ┗━━ 📓 enable_dns_over_https: False
┗━━ 📂 foxyproxy
    ┗━━ 📂 proxies
        ┣━━ 📂 title
        ┃   ┣━━ 📓 title: My company
        ┃   ┗━━ 📓 color: #66cc66
        ┣━━ 📂 title
        ┃   ┣━━ 📓 title: An other company
        ┃   ┗━━ 📓 color: #cc66cc
        ┗━━ 📂 title
            ┣━━ 📓 title: WPAD
            ┗━━ 📓 color: #1166cc