{"id":15644972,"url":"https://github.com/jtyr/ansible-config_encoder_filters","last_synced_at":"2025-04-28T16:23:13.861Z","repository":{"id":49182034,"uuid":"59566487","full_name":"jtyr/ansible-config_encoder_filters","owner":"jtyr","description":"Ansible role used to deliver the Config Encoder Filters.","archived":false,"fork":false,"pushed_at":"2023-08-25T13:56:03.000Z","size":113,"stargazers_count":61,"open_issues_count":3,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-30T11:11:52.391Z","etag":null,"topics":["ansible","ansible-filters","apache","erlang","haproxy","ini","json","logstash","nginx","pam","toml","xml","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jtyr.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-24T11:16:34.000Z","updated_at":"2024-09-12T09:40:07.000Z","dependencies_parsed_at":"2024-10-03T12:06:19.465Z","dependency_job_id":"7b7c0422-b3da-45eb-86dc-a06d5c0e5d49","html_url":"https://github.com/jtyr/ansible-config_encoder_filters","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyr%2Fansible-config_encoder_filters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyr%2Fansible-config_encoder_filters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyr%2Fansible-config_encoder_filters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyr%2Fansible-config_encoder_filters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtyr","download_url":"https://codeload.github.com/jtyr/ansible-config_encoder_filters/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251343240,"owners_count":21574327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-filters","apache","erlang","haproxy","ini","json","logstash","nginx","pam","toml","xml","yaml"],"created_at":"2024-10-03T12:03:48.907Z","updated_at":"2025-04-28T16:23:13.846Z","avatar_url":"https://github.com/jtyr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Config Encoder Filters\n======================\n\nThis is an Ansible role used to deliver the Config Encoder Filters as\na dependency of another Ansible role.\n\n.. image:: https://travis-ci.org/jtyr/ansible-config_encoder_filters.svg?branch=master\n    :target: https://travis-ci.org/jtyr/ansible-config_encoder_filters\n\n\nTable of Contents\n-----------------\n\n- Motivation_\n- Example_\n- Usage_\n- Installation_\n- `Supported encoders`_\n    - encode_apache_\n    - encode_erlang_\n    - encode_haproxy_\n    - encode_ini_\n    - encode_json_\n    - encode_logstash_\n    - encode_lua_\n    - encode_nginx_\n    - encode_pam_\n    - encode_toml_\n    - encode_xml_\n    - encode_yaml_\n- Utilities_\n    - template_replace_\n- Testing_\n- License_\n- Author_\n\n----\n\n\n.. _Motivation:\n\nMotivation\n----------\n\nAnsible Galaxy contains a lot of useful roles. Some of them exist in\nmany variations which differ only by their parameterization. The\nparameterization is often used mainly in templates which generate the\nconfiguration file. A good example such issues are roles for Nginx of\nwhich you can find almost 200 in the Ansible Galaxy.\n\nNginx is possible to configure in infinite number of ways and therefore\nis almost impossible to create an Ansible template file which would\ncapture all possible variations of the configuration. Even if a suitable\nroles is found, users often want to customize even more. This is where\npeople normally clone the role and add parameters they are missing. Some\npeople try to get the change back into the original role by creating a\npull request (PR) but sometimes such change is not accepted by the\nmaintainer of the original role and the user ends up maintaining his/her\nown clone forever.\n\nThis is why the Config Encoder filters were developed to facilitate the\ncreation of Ansible roles with universal configuration. The structure of\nthe configuration file is described as a YAML data structure stored in a\nvariable. The variable together with he Config Encoder filter is then\nused in the template file which is used to generate the final\nconfiguration file. This approach allows to shift the paradigm of\nthinking about configuration files as templates to thinking about them as\ndata structures. The data structure can be dynamically generated which\nallows to create truly universal configuration.\n\n\n.. _Example:\n\nExample\n-------\n\nImagine the following INI file:\n\n.. code:: ini\n\n    [section1]\n    option11=value11\n    option12=value12\n\nSuch configuration file can be described as a YAML data structure:\n\n.. code:: yaml\n\n    myapp_config:\n      section1:\n        option11: value11\n        option12: value12\n\nThe variable is then used together with the ``encode_ini`` Config Encoder\nfilter in the template file ``myapp.cfg.j2`` like this:\n\n.. code:: jinja2\n\n    {{ myapp_config | encode_ini }}\n\nAnd finally, the template file is used in a task like this:\n\n.. code:: yaml\n\n    - name: Create config file\n      template:\n        src: myapp.cfg.j2\n        dest: /etc/myapp/myapp.cfg\n\nWhen the task is executed, it creates exactly the same file as the\noriginal INI file.\n\nSo we can describe the configuration as a data structure which is then\nconverted into the final configuration file format with the Config\nEncoder filter.\n\nIn order to change the above configuration, we would have to overwrite\nthe ``myapp_config`` which is not very practical. Therefore we break the\nmonolithic variable into a set of variables which will allow us to change\nany part of the configuration without the need to overwrite the whole\ndata structure:\n\n.. code:: yaml\n\n    myapp_config_section1_option11: value11\n    myapp_config_section1_option12: value12\n\n    myapp_config_section1__default:\n      option11: \"{{ myapp_config_section1_option11 }}\"\n      option12: \"{{ myapp_config_section1_option12 }}\"\n\n    myapp_config_section1__custom: {}\n\n    myapp_config_default:\n      section1: \"{{\n        myapp_config_section1__default | combine(\n        myapp_config_section1__custom) }}\"\n\n    myapp_config__custom: {}\n\n    myapp_config: \"{{\n      myapp_config__default | combine(\n      myapp_config__custom) }}\"\n\nLike this, if we want to change the value of the ``option11``, we only\noverride the variable ``myapp_config_section1_option11``:\n\n.. code:: yaml\n\n    myapp_config_section1_option11: My new value\n\nIf we want to add a new option into the ``section1``, we add it into the\nvariable ``myapp_config_section1__custom`` which is then merged with the\ndefault list of options:\n\n.. code:: yaml\n\n    myapp_config_section1__custom:\n      section13: value13\n\nAnd if we want to add a new section, we add it into the variable\n``myapp_config__custom`` which is then merged with the default list of\nsections:\n\n.. code:: yaml\n\n    myapp_config__custom:\n      section2:\n        option21: value21\n\nThe above is showing an example for INI configuration files only but the\nsame principle is possible to use for all the supported Config Encoders\nlisted bellow.\n\n\n.. _Usage:\n\nUsage\n-----\n\nConfig Encoder filters can be used in any Ansible role by adding the\n``config_encoder_filters`` role into the list of dependencies in the\n``meta/main.yml`` file:\n\n.. code:: yaml\n\n    dependencies:\n      - config_encoder_filters\n\nThe usage directy from a Playbook requires to add the\n``config_encoder_filters`` into the list of roles:\n\n.. code:: yaml\n\n    - name: My test Play\n      hosts: all\n      roles:\n        - config_encoder_filters\n      tasks:\n        - name: Create config file\n          template:\n            src: my.conf.j2\n            dest: /tmp/my.conf\n\n\n.. _Installation:\n\nInstallation\n------------\n\nThe role can be downloaded either via Ansible Galaxy command:\n\n.. code:: shell\n\n    $ ansible-galaxy install jtyr.config_encoder_filters,master,config_encoder_filters\n\nor via Ansible Gallaxy requirements file:\n\n.. code:: shell\n\n    $ cat ./requirements.yaml\n    ---\n\n    - src: https://github.com/jtyr/ansible-config_encoder_filters.git\n      name: config_encoder_filters\n    $ ansible-galaxy -r ./requirements.yaml\n\nor via Git:\n\n.. code:: shell\n\n    $ git clone https://github.com/jtyr/ansible-config_encoder_filters.git config_encoder_filters\n\n\n.. _`Supported encoders`:\n\nSupported encoders\n------------------\n\nThe following is the list of supported Config Encoder filters. Each\nfilter requires special data structure as its input. Each filter also has\na set of parameters which can modify the behaviour of the filter.\n\n\n.. _encode-apache:\n\nencode_apache\n^^^^^^^^^^^^^\n\nThis filter helps to create configuration in the format used by Apache\nweb server. The expected data structure is the following:\n\n.. code:: yaml\n\n    my_apache_vhost:\n      content:\n        - sections:\n          - name: VirtualHost\n            param: \"*:80\"\n            content:\n              - options:\n                - DocumentRoot: /www/example1\n                - ServerName: www.example.com\n                - ErrorLog: /var/log/httpd/www.example.com-error_log\n                - CustomLog:\n                  - /var/log/httpd/www.example.com-access_log\n                  - common\n                - \"#\": Other directives here ...\n\nThe variable starts with ``content`` which can contain list of\n``sections`` or ``options``. ``sections`` then contain list of individual\nsections which has the ``name``, ``param`` and ``content`` parameter. The\n``content`` can again contain a list of `sections`` or ``options``.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_apache_vhost | encode_apache }}\n\nThe output of such template would be:\n\n.. code:: apache\n\n    \u003cVirtualHost *:80\u003e\n      DocumentRoot /www/example1\n      ServerName www.example.com\n      ErrorLog /var/log/httpd/www.example.com-error_log\n      CustomLog /var/log/httpd/www.example.com-access_log common\n      # \"Other directives here ...\"\n    \u003c/VirtualHost\u003e\n\nThe filter can have the following parameters:\n\n- ``convert_bools=false``\n\n  Indicates whether Boolean values presented as a string should be\n  converted to a real Boolean value. For example ``var1: 'True'`` would\n  be represented as a string but by using the ``convert_bools=true`` it\n  will be converted into Boolean like it would be defined like ``var1:\n  true``.\n\n- ``convert_nums=false``\n\n  Indicates whether number presented as a string should be converted to\n  number. For example ``var1: '123'`` would be represented as a string\n  but by using the ``convert_nums=true`` it will be converted it to a\n  number like it would be defined like ``var1: 123``. It's also possible\n  to use the YAML type casting to convert string to number (e.g. ``!!int\n  \"1234\"``, ``!!float \"3.14\"``).\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n- ``quote_all_nums=false``\n\n  Number values are not quoted by default. This parameter will force to\n  quote all numbers.\n\n- ``quote_all_strings=false``\n\n  String values are quoted only if they contain a space. This parameter\n  will force to quote all strings regardless if the they contain the\n  space or not.\n\n\n.. _encode-erlang:\n\nencode_erlang\n^^^^^^^^^^^^^\n\nThis filter helps to create configuration in the Erlang format. The\nexpected data structure is the following:\n\n.. code:: yaml\n\n    my_rabbitmq_config:\n      - rabbit:\n        - tcp_listeners:\n          - '\"127.0.0.1\"': 5672\n        - ssl_listeners:\n          - 5671\n        - ssl_options:\n          - cacertfile: /path/to/testca/cacert.pem\n          - certfile: /path/to/server/cert.pem\n          - keyfile: /path/to/server/key.pem\n          - verify: :verify_peer\n          - fail_if_no_peer_cert: true\n        - cluster_nodes:\n            ::\n              -\n                - :\"'rabbit@node1'\"\n                - :\"'rabbit@node2'\"\n              - :disc\n\nThe variable consists of a lists of dictionaries. The value of the key-value\npair can be another list or simple value like a string or a number. Erlang\ntuples can be enforced by prepending the value with the special character\nspecified in the ``atom_value_indicator``. Order in tuple can be achieved by\nusing special construction as shown for the ``cluste_nodes`` tuple from the\nabove example. The indicator starting this special construction can be set with\nthe parameter ``ordered_tuple_indicator``.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_rabbitmq_config | encode_erlang }}\n\nThe output of such template would be:\n\n.. code:: erlang\n\n    [\n      {rabbit, [\n          {tcp_listeners, [\n              {\"127.0.0.1\", 5672}\n          ]},\n          {ssl_listeners, [\n            5671\n          ]},\n          {ssl_options, [\n              {cacertfile, \"/path/to/testca/cacert.pem\"},\n              {certfile, \"/path/to/server/cert.pem\"},\n              {keyfile, \"/path/to/server/key.pem\"},\n              {verify, verify_peer},\n              {fail_if_no_peer_cert, true}\n          ]},\n          {cluster_nodes,\n            {[\n              'rabbit@node1',\n              'rabbit@node2'\n            ], disc}}\n      ]}\n    ].\n\nThe filter can have the following parameters:\n\n- ``atom_value_indicator=\":\"``\n\n  The value of this parameter indicates the string which must be\n  prepended to a string value to treat it as an atom value.\n\n- ``convert_bools=false``\n\n  Indicates whether Boolean values presented as a string should be\n  converted to a real Boolean value. For example ``var1: 'True'`` would\n  be represented as a string but by using the ``convert_bools=true`` it\n  will be converted into Boolean like it would be defined like ``var1:\n  true``.\n\n- ``convert_nums=false``\n\n  Indicates whether number presented as a string should be converted to\n  number. For example ``var1: '123'`` would be represented as a string\n  but by using the ``convert_nums=true`` it will be converted it to a\n  number like it would be defined like ``var1: 123``. It's also possible\n  to use the YAML type casting to convert string to number (e.g. ``!!int\n  \"1234\"``, ``!!float \"3.14\"``).\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n- ``ordered_tuple_indicator=\":\"``\n\n  Indicator used to start the special construction with ordered tuple.\n\n\n.. _encode-haproxy:\n\nencode_haproxy\n^^^^^^^^^^^^^^\n\nThis filter helps to create configuration in the format used in Haproxy.\nThe expected data structure is the following:\n\n.. code:: yaml\n\n    my_haproxy_config:\n      - global:\n        - daemon\n        - maxconn 256\n      - \"# This is the default section\"\n      - defaults:\n        - mode http\n        - timeout:\n            - connect 5000ms\n            - client 50000ms\n            - server 50000ms\n      - frontend http-in:\n        - \"# This is the bind address/port\"\n        - bind *:80\n        - default_backend servers\n        - backend servers\n        - server server1 127.0.0.1:8000 maxconn 32\n\nThe variable is a list which can contain a simple string value or a dictionary\nwhich indicates a section.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_haproxy_config | encode_haproxy }}\n\nThe output of such template would be:\n\n.. code:: haproxy\n\n    global\n      daemon\n      maxconn 256\n\n    # This is the default section\n    defaults\n      mode http\n      timeout connect 5000ms\n      timeout client 50000ms\n      timeout server 50000ms\n\n    frontend http-in\n      # This is the bind address/port\n      bind *:80\n      default_backend servers\n      backend servers\n      server server1 127.0.0.1:8000 maxconn 32\n\nThe filter can have the following parameters:\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n\n.. _encode-ini:\n\nencode_ini\n^^^^^^^^^^\n\nThis filter helps to create configuration in the INI format. The expected\ndata structure is the following:\n\n.. code:: yaml\n\n    my_rsyncd_config:\n      uid: nobody\n      gid: nobody\n      use chroot: no\n      max connections: 4\n      syslog facility: local5\n      pid file: /run/rsyncd.pid\n      ftp:\n        path: /srv/ftp\n        comment: ftp area\n\nThe variable consist of dictionaries which can be nested. If the value of the\nkey-value pair on the first level is of a simple type (string, number, boolean),\nsuch pair is considered to be global and gets processed first. If the value of\nthe key-value pair on the first level is another dictionary, the key is\nconsidered to be the name of the section and the inner dictionary as properties\nof the section.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_rsyncd_config | encode_ini }}\n\nThe output of such template would be:\n\n.. code:: ini\n\n    gid=nobody\n    max connections=4\n    pid file=/run/rsyncd.pid\n    syslog facility=local5\n    uid=nobody\n    use chroot=False\n\n    [ftp]\n    comment=ftp area\n    path=/srv/ftp\n\nThe special value :code:`!!!null` can be used, to create a key without any value.\nThis must be wrapped in quotes, to avoid being evaluated as a YAML tag.\n\nTake the following data structure:\n\n.. code:: yaml\n\n    config:\n      myconf:\n        key: value\n        keyWithoutValue: '!!!null'\n\nThis would become:\n\n.. code:: ini\n\n    [myconf]\n    key=value\n    keyWithoutValue\n\nThe filter can have the following parameters:\n\n- ``comment=\"#\"``\n\n  Sign used to comment out lines when `section_is_comment=true`.\n\n- ``delimiter=\"=\"``\n\n  Sign separating the *property* and the *value*. By default it's set to\n  ``'='`` but it can also be set for example to ``' = '``.\n\n- ``indent=\"\"``\n\n  Indent the keys with the specified string. E.g. ``indent=\"\\t\"``.\n\n- ``quote=\"\"``\n\n  Sets the quoting of the value. Use ``quote=\"'\"`` or ``quote='\"'``.\n\n- ``section_is_comment=false``\n\n  If this parameter is set to ``true``, the section value will be used as\n  a comment for the following properties of the section.\n\n- ``ucase_prop=false``\n\n  Indicates whether the *property* should be made upper case.\n\n\n.. _encode-json:\n\nencode_json\n^^^^^^^^^^^\n\nThis filter helps to create configuration in the JSON format. The\nexpected data structure is the following:\n\n.. code:: yaml\n\n    my_sensu_client_config:\n      client:\n        name: localhost\n        address: 127.0.0.1\n        subscriptions:\n          - test\n\nBecause JSON is very similar to YAML, the variable consists of\ndictionaries of which value can be either an simple type (number, string,\nboolean), list or another dictionary. All can be nested in any number of\nlevels.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_sensu_client_config | encode_json }}\n\nThe output of such template would be:\n\n.. code:: json\n\n    {\n      \"client\": {\n        \"address\": \"127.0.0.1\",\n        \"name\": \"localhost\",\n        \"subscriptions\": [\n          \"test\"\n        ]\n      }\n    }\n\nThe filter can have the following parameters:\n\n- ``convert_bools=false``\n\n  Indicates whether Boolean values presented as a string should be\n  converted to a real Boolean value. For example ``var1: 'True'`` would\n  be represented as a string but by using the ``convert_bools=true`` it\n  will be converted into Boolean like it would be defined like ``var1:\n  true``.\n\n- ``convert_nums=false``\n\n  Indicates whether number presented as a string should be converted to\n  number. For example ``var1: '123'`` would be represented as a string\n  but by using the ``convert_nums=true`` it will be converted it to a\n  number like it would be defined like ``var1: 123``. It's also possible\n  to use the YAML type casting to convert string to number (e.g. ``!!int\n  \"1234\"``, ``!!float \"3.14\"``).\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n\n.. _encode-logstash:\n\nencode_logstash\n^^^^^^^^^^^^^^^\n\nThis filter helps to create configuration in the format used by Logstash.\nThe expected data structure is the following:\n\n.. code:: yaml\n\n    my_logstash_config:\n      - :input:\n          - :file:\n              path: /var/log/httpd/access_log\n              start_position: beginning\n      - :filter:\n          - ':if [path] =~ \"access\"':\n              - :mutate:\n                  replace:\n                    type: apache_access\n              - :grok:\n                  match:\n                    message: \"%{COMBINEDAPACHELOG}\"\n              - :date:\n                  match:\n                    - timestamp\n                    - dd/MMM/yyyy:HH:mm:ss Z\n          - ':else if [path] =~ \"error\"':\n              - :mutate:\n                  replace:\n                    type: \"apache_error\"\n          - :else:\n              - :mutate:\n                  replace:\n                    type: \"random_logs\"\n      - :output:\n          - :elasticsearch:\n              hosts:\n                - localhost:9200\n          - :stdout:\n              codec: rubydebug\n\nThe variable consists of a list of sections where each section is\nprefixed by a special character specified by the ``section_prefix``\n(``:`` by default). The value of the top level sections can be either\nanother section or a dictionary. The value of the dictionary can be a\nsimple value, list or another dictionary.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_logstash_config | encode_logstash }}\n\nThe output of such template would be:\n\n.. code:: logstash\n\n    input {\n      file {\n        path =\u003e \"/var/log/httpd/access_log\"\n        start_position =\u003e \"beginning\"\n      }\n    }\n    filter {\n      if [path] =~ \"access\" {\n        mutate {\n          replace =\u003e {\n            \"type\" =\u003e \"apache_access\"\n          }\n        }\n        grok {\n          match =\u003e {\n            \"message\" =\u003e \"%{COMBINEDAPACHELOG}\"\n          }\n        }\n        date {\n          match =\u003e [\n            \"timestamp\",\n            \"dd/MMM/yyyy:HH:mm:ss Z\"\n          ]\n        }\n      }\n      else if [path] =~ \"error\" {\n        mutate {\n          replace =\u003e {\n            \"type\" =\u003e \"apache_error\"\n          }\n        }\n      }\n      else {\n        mutate {\n          replace =\u003e {\n            \"type\" =\u003e \"random_logs\"\n          }\n        }\n      }\n    }\n    output {\n      elasticsearch {\n        hosts =\u003e [\n          \"localhost:9200\"\n        ]\n      }\n      stdout {\n        codec =\u003e \"rubydebug\"\n      }\n    }\n\nThe filter can have the following parameters:\n\n- ``backslash_ignore_prefix='@@@'``\n\n  This parameter defines a sets of characters than can be prepended to a string\n  to prevent backslahes from being escaped in the resulting configuration (e.g.\n  ``\"@@@sshd(?:\\[%{POSINT:[system][auth][pid]}\\])?:\"`` will turn to\n  ``\"sshd(?:\\[%{POSINT:[system][auth][pid]}\\])?:\"`` instead of to\n  ``\"sshd(?:\\\\[%{POSINT:[system][auth][pid]}\\\\])?:\"``).\n\n- ``convert_bools=false``\n\n  Indicates whether Boolean values presented as a string should be\n  converted to a real Boolean value. For example ``var1: 'True'`` would\n  be represented as a string but by using the ``convert_bools=true`` it\n  will be converted into Boolean like it would be defined like ``var1:\n  true``.\n\n- ``convert_nums=false``\n\n  Indicates whether number presented as a string should be converted to\n  number. For example ``var1: '123'`` would be represented as a string\n  but by using the ``convert_nums=true`` it will be converted it to a\n  number like it would be defined like ``var1: 123``. It's also possible\n  to use the YAML type casting to convert string to number (e.g. ``!!int\n  \"1234\"``, ``!!float \"3.14\"``).\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n- ``section_prefix=\":\"``\n\n  This parameter specifies which character will be used to identify the\n  Logstash section.\n\n\n.. _encode-lua:\n\nencode_lua\n^^^^^^^^^^\n\nThis filter helps to create configuration in a Lua friendly format.\nThe expected data structure is the following:\n\n.. code:: yaml\n\n    my_lua_config:\n      fork: false\n      external_addresses:\n        - 1.2.3.4\n        - 5.6.7.8\n      admins:\n        - admin@example.com\n      contact_info:\n        abuse: abuse@example.com\n        admin: admin@example.com\n\nLua is a small scripting language, often embedded into C/C++ applications.\nThis encoder does a best effort to match configuration files seen in the wild,\nwhile allowing the user to further customize how the final output is rendered.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_lua_config | encode_lua }}\n\nThe output of such a template would be:\n\n.. code:: lua\n\n    fork = false;\n    external_addresses = {\n        \"1.2.3.4\";\n        \"5.6.7.8\";\n    }\n    admins = {\n        \"admin@example.com\";\n    }\n    contact_info = {\n        abuse = \"abuse@example.com\";\n        admin = \"admin@example.com\";\n    }\n\nThe filter can have the following parameters:\n\n- ``convert_bools=false``\n\n  Indicates whether Boolean values presented as a string should be\n  converted to a real Boolean value. For example ``var1: 'True'`` would\n  be represented as a string but by using the ``convert_bools=true`` it\n  will be converted into Boolean like it would be defined like ``var1:\n  true``.\n\n- ``convert_nums=false``\n\n  Indicates whether number presented as a string should be converted to\n  number. For example ``var1: '123'`` would be represented as a string\n  but by using the ``convert_nums=true`` it will be converted it to a\n  number like it would be defined like ``var1: 123``. It's also possible\n  to use the YAML type casting to convert string to number (e.g. ``!!int\n  \"1234\"``, ``!!float \"3.14\"``).\n\n- ``sort_keys=false``\n\n  Indicates whether the keys should be sorted when the output is rendered,\n  or left to python's implicit handling of dict ordering.\n\n- ``indent=\"    \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n\n.. _encode-nginx:\n\nencode_nginx\n^^^^^^^^^^^^\n\nThis filter helps to create configuration in the format used by Nginx\nweb server. The expected data structure is the following:\n\n.. code:: yaml\n\n    my_nginx_vhost_config:\n      - server:\n        - listen 80\n        - server_name $hostname\n        - \"location /\":\n          - root /srv/www/myapp\n          - index index.html\n\nAs Nginx configuration is order sensitive, the all configuration is\ndefined as a nested list. As it would be difficult to recognize how many\nelements each configuration definition has, the list item value is no\nfurther separated into key/value dictionary. Every line of the\nconfiguration is treated either as a key indicating another nested list\nor simply as a string.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_nginx_vhost | encode_nginx }}\n\nThe output of such template would be:\n\n.. code:: nginx\n\n    server {\n      listen 80;\n      server_name $hostname;\n\n      location / {\n        root /srv/www/myapp;\n        index index.html;\n      }\n    }\n\nThe filter can have the following parameters:\n\n- ``block_semicolon=false``\n\n  Allows to add a semicolon to the end of each block.\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n- ``semicolon=';'``\n\n  Semicolon character. Set this to empty string to ignore all semicolons.\n\n- ``semicolon_ignore_postfix='!;'``\n\n  If the line ends with ``!;`` then don't add the final semicolon.\n\n\n.. _encode-pam:\n\nencode_pam\n^^^^^^^^^^\n\nThis filter helps to create configuration in the format user by Linux\nPluggable Authentication Modules (PAM). The expected data structure is\nthe following:\n\n.. code:: yaml\n\n    my_system_auth_config:\n      aa:\n        type: auth\n        control: required\n        path: pam_unix.so\n        args:\n          - try_first_pass\n          - nullok\n      bb:\n        type: auth\n        control: optional\n        path: pam_permit.so\n      cc:\n        type: auth\n        control: required\n        path: pam_env.so\n      dd:\n        type: account\n        control: required\n        path: pam_unix.so\n      ee:\n        type: account\n        control: optional\n        path: pam_permit.so\n      ff:\n        type: account\n        control: required\n        path: pam_time.so\n      gg:\n        type: password\n        control: required\n        path: pam_unix.so\n        args:\n          - try_first_pass\n          - nullok\n          - sha512\n          - shadow\n      hh:\n        type: password\n        control: optional\n        path: pam_permit.so\n        args:\n      ii:\n        type: session\n        control: required\n        path: pam_limits.so\n      jj:\n        type: session\n        control: required\n        path: pam_unix.so\n      kk:\n        type: session\n        control: optional\n        path: pam_permit.so\n\nThe variable is a dictionary of which the key is a labels and the value\nis the PAM rule. The label is used to order the PAM rules. Using labels\nwith even number of characters allows to insert another rule in between\nof any two rules.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_system_auth_config | encode_pam }}\n\nThe output of such template would be:\n\n.. code:: pam\n\n    auth  required  pam_unix.so  try_first_pass nullok\n    auth  optional  pam_permit.so\n    auth  required  pam_env.so\n\n    account  required  pam_unix.so\n    account  optional  pam_permit.so\n    account  required  pam_time.so\n\n    password  required  pam_unix.so  try_first_pass nullok sha512 shadow\n    password  optional  pam_permit.so\n\n    session  required  pam_limits.so\n    session  required  pam_unix.so\n    session  optional  pam_permit.so\n\nThe filter can have the following parameters:\n\n- ``print_label=false``\n\n  Print labels as a comment in the output.\n\n- ``separate_types=true``\n\n  Add a newline between the groups of types.\n\n- ``separator=\"  \"``\n\n  Separator between the collection of tokens.\n\n\n.. _encode-toml:\n\nencode_toml\n^^^^^^^^^^^\n\nThis filter helps to create configuration in the TOML format. The\nexpected data structure is the following:\n\n.. code:: yaml\n\n    my_grafana_ldap_config:\n      verbose_logging: false\n      servers:\n        - host: 127.0.0.1\n          port: 389\n          use_ssl: no\n          start_tls: no\n          ssl_skip_verify: no\n          bind_dn: cn=admin,dc=grafana,dc=org\n          bind_password: grafana\n          search_filter: (cn=%s)\n          search_base_dns:\n            - dc=grafana,dc=org\n        - attributes:\n            name: givenName\n            surname: sn\n            username: cn\n            member_of: memberOf\n            email: email\n        - group_mappings:\n            - group_dn: cn=admins,dc=grafana,dc=org\n              org_role: Admin\n            - group_dn: cn=users,dc=grafana,dc=org\n              org_role: Editor\n            - group_dn: \"*\"\n              org_role: Viewer\n\nThe variable is a dictionary of which value can be either a simple type\n(number, string, boolean), list or another dictionary. The dictionaries\nand lists can be nested.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_grafana_ldap_config | encode_toml }}\n\nThe output of such template would be:\n\n.. code:: toml\n\n    verbose_logging = false\n\n    [[servers]]\n    host = \"127.0.0.1\"\n    port = 389\n    use_ssl = false\n    start_tls = false\n    ssl_skip_verify = false\n    bind_dn = \"cn=admin,dc=grafana,dc=org\"\n    bind_password = 'grafana'\n    search_filter = \"(cn=%s)\"\n    search_base_dns = [\"dc=grafana,dc=org\"]\n\n    [servers.attributes]\n    name = \"givenName\"\n    surname = \"sn\"\n    username = \"cn\"\n    member_of = \"memberOf\"\n    email =  \"email\"\n\n    [[servers.group_mappings]]\n    group_dn = \"cn=admins,dc=grafana,dc=org\"\n    org_role = \"Admin\"\n\n    [[servers.group_mappings]]\n    group_dn = \"cn=users,dc=grafana,dc=org\"\n    org_role = \"Editor\"\n\n    [[servers.group_mappings]]\n    group_dn = \"*\"\n    org_role = \"Viewer\"\n\nThe filter can have the following parameters:\n\n- ``convert_bools=false``\n\n  Indicates whether Boolean values presented as a string should be\n  converted to a real Boolean value. For example ``var1: 'True'`` would\n  be represented as a string but by using the ``convert_bools=true`` it\n  will be converted into Boolean like it would be defined like ``var1:\n  true``.\n\n- ``convert_nums=false``\n\n  Indicates whether number presented as a string should be converted to\n  number. For example ``var1: '123'`` would be represented as a string\n  but by using the ``convert_nums=true`` it will be converted it to a\n  number like it would be defined like ``var1: 123``. It's also possible\n  to use the YAML type casting to convert string to number (e.g. ``!!int\n  \"1234\"``, ``!!float \"3.14\"``).\n\n- ``quote='\"'``\n\n  Sets the quoting of the value. Use ``quote=\"'\"`` or ``quote='\"'``.\n\n\n.. _encode-xml:\n\nencode_xml\n^^^^^^^^^^\n\nThis filter helps to create configuration in the XML format. The expected\ndata structure is the following:\n\n.. code:: yaml\n\n    my_oddjob_config:\n      - oddjobconfig:\n        - service:\n          - ^name: com.redhat.oddjob\n          - object:\n            - ^name: /com/redhat/oddjob\n            - interface:\n              - ^name: com.redhat.oddjob\n              - method:\n                - ^name: listall\n                - allow:\n                  - ^min_uid: 0\n                  - ^max_uid: 0\n              - method:\n                - ^name: list\n                - allow: ''\n              - method:\n                - ^name: quit\n                - allow:\n                  - ^user: root\n              - method:\n                - ^name: reload\n                - allow:\n                  - ^user: root\n        - include:\n          - ^ignore_missing: \"yes\"\n          - /etc/oddjobd.conf.d/*.conf\n        - include:\n          - ^ignore_missing: \"yes\"\n          - /etc/oddjobd-local.conf\n\nThe variable can be a list of dictionaries, lists or strings. This config\nencoder does not handle mixed content very well so the safest way how to\ninclude mixed content is to define it as a string and use the parameter\n``escape_xml=false``. This config encoder also produces no XML declaration.\nAny XML declaration or DOCTYPE must be a part of the template file.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_oddjob_config | encode_xml }}\n\nThe output of such template would be:\n\n.. code:: xml\n\n    \u003coddjobconfig\u003e\n      \u003cservice name=\"com.redhat.oddjob\"\u003e\n        \u003cobject name=\"/com/redhat/oddjob\"\u003e\n          \u003cinterface name=\"com.redhat.oddjob\"\u003e\n            \u003cmethod name=\"listall\"\u003e\n              \u003callow min_uid=\"0\" max_uid=\"0\" /\u003e\n            \u003c/method\u003e\n            \u003cmethod name=\"list\"\u003e\n              \u003callow /\u003e\n            \u003c/method\u003e\n            \u003cmethod name=\"quit\"\u003e\n              \u003callow user=\"root\" /\u003e\n            \u003c/method\u003e\n            \u003cmethod name=\"reload\"\u003e\n              \u003callow user=\"root\" /\u003e\n            \u003c/method\u003e\n          \u003c/interface\u003e\n        \u003c/object\u003e\n      \u003c/service\u003e\n      \u003cinclude ignore_missing=\"yes\"\u003e/etc/oddjobd.conf.d/*.conf\u003c/include\u003e\n      \u003cinclude ignore_missing=\"yes\"\u003e/etc/oddjobd-local.conf\u003c/include\u003e\n    \u003c/oddjobconfig\u003e\n\nThe filter can have the following parameters:\n\n- ``attribute_sign=\"^\"``\n\n  XML attribute indicator.\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n\n.. _encode-yaml:\n\nencode_yaml\n^^^^^^^^^^^\n\nThis filter helps to create configuration in the YAML format. The\nexpected data structure is the following:\n\n.. code:: yaml\n\n    my_mongodb_config:\n      systemLog:\n        destination: file\n        logAppend: true\n        path: /var/log/mongodb/mongod.log\n      storage:\n        dbPath: /var/lib/mongo\n        journal:\n          enabled: true\n      processManagement:\n        fork: true\n        pidFilePath: /var/run/mongodb/mongod.pid\n      net:\n        port: 27017\n        bindIp: 127.0.0.1\n\nThe variable is ordinary YAML. The only purpose of this encoder filter is\nto be able to convert YAML data structure into the string in a template\nfile in unified way compatible with the other config encoders.\n\nThe above variable can be used in the template file like this:\n\n.. code:: jinja2\n\n    {{ my_mongodb_config | encode_yaml }}\n\nThe output of such template would be:\n\n.. code:: yaml\n\n    net:\n      bindIp: \"127.0.0.1\"\n      port: 27017\n    processManagement:\n      fork: true\n      pidFilePath: \"/var/run/mongodb/mongod.pid\"\n    storage:\n      dbPath: \"/var/lib/mongo\"\n      journal:\n        enabled: true\n    systemLog:\n      destination: \"file\"\n      logAppend: true\n      path: \"/var/log/mongodb/mongod.log\"\n\nThe filter can have the following parameters:\n\n- ``block_prefix=';;;'``\n\n  Allows to maintain block signs in the output.\n\n  .. code:: yaml\n\n      aaa: |-\n        ;;;|-\n        bbb = ccc\n        ddd = eee\n\n- ``convert_bools=false``\n\n  Indicates whether Boolean values presented as a string should be\n  converted to a real Boolean value. For example ``var1: 'True'`` would\n  be represented as a string but by using the ``convert_bools=true`` it\n  will be converted into Boolean like it would be defined like ``var1:\n  true``.\n\n- ``convert_nums=false``\n\n  Indicates whether number presented as a string should be converted to\n  number. For example ``var1: '123'`` would be represented as a string\n  but by using the ``convert_nums=true`` it will be converted it to a\n  number like it would be defined like ``var1: 123``. It's also possible\n  to use the YAML type casting to convert string to number (e.g. ``!!int\n  \"1234\"``, ``!!float \"3.14\"``).\n\n- ``indent=\"  \"``\n\n  Defines the indentation unit.\n\n- ``level=0``\n\n  Indicates the initial level of the indentation. Value ``0`` starts\n  indenting from the beginning of the line. Setting the value to higher\n  than ``0`` indents the content by ``indent * level``.\n\n- ``quote='\"'``\n\n  Sets the quoting of the value. Use ``quote=\"'\"`` or ``quote='\"'``.\n\n\n.. _Utilities:\n\nUtilities\n---------\n\nThe followng is a list of utilities that can be used in conjunction with the\nConfig Encoder filters.\n\n\n.. _template-replace:\n\ntemplate_replace\n^^^^^^^^^^^^^^^^\n\nThis filter allows to use extra templating layer which gets processed during\nthe template file processing. That can be useful if it's necessary to create\nrepetitive but slightly different definitions inside the template file.\n\nThe extra templating layer is represented by a templating variable which\ncontains specially decorated variables which get replaced by its real value at\nthe time of template file processing. The template variable can be composed\ndynamically which provides extra flexibility that would otherwise have to be\nhardcoded in the template file.\n\nThe filter expects the template variable containing the specially decorated\nvariables as its input. The filter has one parameter which is used to replaced\nthe specially decorated variables in the template variable.\n\nLet's have a look at an example of such usage:\n\n.. code:: yaml\n\n    # The variable used as the replacement in the template variable\n    my_clients:\n      - host: myclient01\n        jobdefs: Default\n        password: Passw0rd1\n        file_retention: 30 days\n      - host: myclient02\n        jobdefs: HomeOnly\n        password: Passw0rd2\n        file_retention: 90 days\n\n    # The actual template variable used in the template file\n    bacula_director_config_job_client:\n      # First template variable containing the specially decorated variables\n      - template:\n          - Job:\n            - Name = Job-{[{ item['jobdefs'] }]}-{[{ item['host'] }]}\n            - Client = {[{ item['host'] }]}-fd\n            - JobDefs = {[{ item['jobdefs'] }]}\n        # Variable used to replace the specially decorated variables\n        items: \"{{ my_clients }}\"\n      # Second template and its items\n      - template:\n          - Client:\n            - Name = {[{ item['host'] }]}-fd\n            - Address = {[{ item['host'] }]}\n            - FD Port = 9102\n            - Catalog = Default\n            - Password = {[{ item['password'] }]}\n            - File Retention = {[{ item['file_retention'] }]}\n            - Job Retention = 3 months\n            - AutoPrune = yes\n        items: \"{{ my_clients }}\"\n\nThe above variable can be used together with the `template_replace` filter in\nthe template file (``bacula-dir.conf.j2``) like this:\n\n.. code:: jinja2\n\n    {% for record in bacula_director_config_job_client %}\n      {%- for item in record['items'] -%}\n        {{ record['template'] | template_replace(item) | encode_nginx }}{{ \"\\n\" }}\n      {%- endfor -%}\n    {% endfor %}\n\nThe template file can be called from the playbook/role like this:\n\n.. code:: yaml\n\n    - name: Configure Bacula Director\n      template:\n        src: bacula-dir.conf.j2\n        dest: /etc/bacula/bacula-dir.conf\n\nAnd the result of such usage is the following:\n\n.. code:: nginx\n\n    Job {\n      Name = Job-Default-myclient01;\n      Client = myclient01-fd;\n      JobDefs = Default;\n    }\n\n    Job {\n      Name = Job-HomeOnly-myclient02;\n      Client = myclient02-fd;\n      JobDefs = HomeOnly;\n    }\n\n    Client {\n      Name = myclient01-fd;\n      Address = myclient01;\n      FD Port = 9102;\n      Catalog = Default;\n      Password = Passw0rd1;\n      File Retention = 30 days;\n      Job Retention = 3 months;\n      AutoPrune = yes;\n    }\n\n    Client {\n      Name = myclient02-fd;\n      Address = myclient02;\n      FD Port = 9102;\n      Catalog = Default;\n      Password = Passw0rd2;\n      File Retention = 90 days;\n      Job Retention = 3 months;\n      AutoPrune = yes;\n    }\n\n\n.. _Testing:\n\nTesting\n-------\n\nAll encoders have a set of unit tests automated through\n`tox \u003chttp://tox.readthedocs.io\u003e`_. Full test can be executed like this:\n\n.. code:: shell\n\n    $ tox\n\nIndividual encoder can be tested like this:\n\n.. code:: shell\n\n    $ tox -- python -m unittest tests.test_config_encoders.TestYaml\n\nIndividual tests can be executed like this:\n\n.. code:: shell\n\n    $ tox -- python -m unittest tests.test_config_encoders.TestYaml.test_string\n\nTests are great source of advanced examples of how to use each of the encoders.\nExplore them in the directory ``tests/files``. The content of the ``.in`` files\nmust be assigned to a variable when using in Ansible. The output in the\n``.out`` files might depend on additional parameters used in the\n``tests/test_config_encoders.py`` file. Testing via Ansible can be executed\nlike this:\n\n.. code:: shell\n\n    $ ansible-playbook -i localhost, tests/test_config_encoders.yaml\n\n\n.. _License:\n\nLicense\n-------\n\nGPLv3\n\n\n.. _Author:\n\nAuthor\n------\n\nJiri Tyr\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtyr%2Fansible-config_encoder_filters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtyr%2Fansible-config_encoder_filters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtyr%2Fansible-config_encoder_filters/lists"}