diff --git a/defaults/main.yml b/defaults/main.yml
index a3a4265..7eb55b4 100644
--- a/defaults/main.yml
+++ b/defaults/main.yml
@@ -1,5 +1,16 @@
 ---
+# Default variables
+# =================
 
+# .. contents:: Sections
+#    :local:
+#
+# ----------------------
+#   ferm configuration
+# ----------------------
+
+# .. envvar:: ferm_enabled
+#
 # Enable or disable iptables management by checking if 'cap_sys_admin' POSIX
 # capability is set on the host.
 ferm_enabled: '{{ True
@@ -9,24 +20,39 @@ ferm_enabled: '{{ True
                            (ansible_local.cap12s.enabled | bool and "cap_net_admin" in ansible_local.cap12s.list))))
                   else False }}'
 
+
+# .. envvar:: ferm_flush
+#
 # Should ferm-rules be flushed when ferm is disabled? The default is
 # true, but you may need set both ``ferm_enabled`` and this to ``False`` if you
 # are running in some container and are not allowed to change
 # iptables.
 ferm_flush: '{{ ferm_enabled | bool }}'
 
+
+# .. envvar:: ferm_packages
+#
 # List of packages to install
 ferm_packages: [ 'ferm', 'patch' ]
 
+
+# .. envvar:: ferm_init_hooks
+#
 # Enable support for executing hooks at certain points in the init script.
 ferm_init_hooks: True
 
+
+# .. envvar:: ferm_domains
+#
 # List of iptables domains enabled in main ferm firewall
 # Currently supported domains:
 #   - 'ip'  - enables IPv4 support (iptables)
 #   - 'ip6' - enables IPv6 support (ip6tables)
 ferm_domains: [ 'ip', 'ip6' ]
 
+
+# .. envvar:: ferm_ansible_controllers
+#
 # Optional list of CIDR hosts which are not included in ssh port recent filter
 # and won't be blocked by the firewall in case of too many connections.
 # Entries are saved in the local facts on remote hosts.
@@ -37,98 +63,234 @@ ferm_domains: [ 'ip', 'ip6' ]
 #       be to use the `debops.sshd` role to configure ssh service.
 ferm_ansible_controllers: []
 
+
+# .. envvar:: ferm_ansible_controllers_ports
+#
 # List of ports which are opened for access from Ansible Controllers
 ferm_ansible_controllers_ports: [ 'ssh' ]
 
-# Default iptables policy for INPUT, OUTPUT and FORWARD chains
+
+# .. envvar:: ferm_default_policy_input
+#
+# Default iptables policy for INPUT chain
 ferm_default_policy_input: 'DROP'
+
+
+# .. envvar:: ferm_default_policy_output
+#
+# Default iptables policy for OUTPUT chain
 ferm_default_policy_output: 'ACCEPT'
+
+
+# .. envvar:: ferm_default_policy_forward
+#
+# Default iptables policy for FORWARD chain
 ferm_default_policy_forward: 'DROP'
 
+
+# -----------------------------------
+#   Rate limit filter configuration
+# -----------------------------------
+
+# .. envvar:: ferm_filter_icmp
+#
 # Manage filtering of ICMP packets using ``hashlimit`` module.
 ferm_filter_icmp: True
+
+
+# .. envvar:: ferm_filter_icmp_limit
+#
+# Rate limit when filtering ICMP packets
 ferm_filter_icmp_limit: '10/second'
+
+
+# .. envvar:: ferm_filter_icmp_burst
+#
+# Burst limit when filtering ICMP packets
 ferm_filter_icmp_burst: '10'
+
+
+# .. envvar:: ferm_filter_icmp_expire
+#
+# Expiration time when filtering ICMP packets
 ferm_filter_icmp_expire: '{{ (60 * 60) }}'
 
+
+# .. envvar:: ferm_filter_syn
+#
 # Manage filtering of TCP SYN packets using ``hashlimit`` module.
 ferm_filter_syn: True
+
+
+# .. envvar:: ferm_filter_syn_limit
+#
+# Rate limit when filtering TCP SYN packets
 ferm_filter_syn_limit: '40/second'
+
+
+# .. envvar:: ferm_filter_syn_burst
+#
+# Burst limit when filtering TCP SYN packets
 ferm_filter_syn_burst: '20'
+
+
+# .. envvar:: ferm_filter_syn_expire
+#
+# Expiration time when filtering TCP SYN packets
 ferm_filter_syn_expire: '{{ (60 * 60) }}'
 
+
+# .. envvar:: ferm_filter_recent
+#
 # Enable recent filter in respective rules. You might need to disable it on
 # certain hosts, like OpenVZ containers that don't have 'recent' module
 # available.
 ferm_filter_recent: True
 
+
+# .. envvar:: ferm_filter_recent_name
+#
 # Name of recent list to block early
 ferm_filter_recent_name: 'badguys'
 
+
+# .. envvar:: ferm_filter_recent_time
+#
 # Length of time in seconds to block recent offenders; if they try connecting
 # before the time is up, timer is reset
 ferm_filter_recent_time: '{{ (60 * 60 * 2) }}'
 
+
+# .. envvar:: ferm_mark_portscan
+#
 # Mark packets on invalid ports as bad guys (block port scanning)
 ferm_mark_portscan: False
 
+
+# -------------------------
+#   Logging configuration
+# -------------------------
+
+# .. envvar:: ferm_log
+#
 # Enable/disable custom ``&log()`` ferm function used in different firewall
 # rules.
 ferm_log: True
 
+
+# .. envvar:: ferm_log_type
+#
 # Select how firewall performs logging. By default, it uses normal syslog
 # calls, there are other ways to log packets listed below.
 ferm_log_type: 'LOG'
 
+
+# .. envvar:: ferm_log_map
+#
 # Dictionary map with actual firewall rules mapped to different log types.
 ferm_log_map:
   'LOG':   'LOG log-ip-options log-prefix "$msg"'
   'ULOG':  'ULOG ulog-nlgroup {{ ferm_log_group }} ulog-prefix "$msg"'
   'NFLOG': 'NFLOG nflog-group {{ ferm_log_group }} nflog-prefix "$msg"'
 
+
+# .. envvar:: ferm_log_target
+#
 # Firewall log target used in the ``&log()`` ferm function.
 ferm_log_target: '{{ ferm_log_map[ferm_log_type] }}'
 
+
+# .. envvar:: ferm_log_limit
+#
 # Limit the amount of packets logged by the firewall.
 ferm_log_limit: '2/min'
 
+
+# .. envvar:: ferm_log_burst
+#
 # Set the burst limit for the logged packets.
 ferm_log_burst: '5'
 
+
+# .. envvar:: ferm_log_group
+#
 # ULOG/NFLOG group used by the firewall logs.
 ferm_log_group: '32'
 
+
+# -----------------------
+#   Rules configuration
+# -----------------------
+
+# .. envvar:: ferm_include_legacy
+#
 # Include legacy firewall rules. This variable should allow for easier
 # transition to the new firewall rules in the future.
 ferm_include_legacy: True
 
+
+# .. envvar:: ferm__rules
+#
 # List of ``iptables`` rules to manage, templates used by these rules are included
 # in :file:`templates/etc/ferm/ferm.d/` directory.
 # Additional variables are described below.
 ferm__rules: []
+
+
+# .. envvar:: ferm__group_rules
+#
+# List of ``iptables`` rules to manage for a host group
 ferm__group_rules: []
+
+
+# .. envvar:: ferm__host_rules
+#
+# List of ``iptables`` rules to manage for an individual host
 ferm__host_rules: []
+
+
+# .. envvar:: ferm__dependent_rules
+#
+# List of ``iptables`` rules to manage depending on other rules
 ferm__dependent_rules: []
 
-# List of iptables INPUT rules to manage, many variables can be found in
-# template files, located in templates/etc/ferm/filter-input.d/ directory.
-# Additional variables are described below.
+
+# .. envvar:: ferm_input_list
+#
+# List of iptables INPUT rules to manage. See :ref:`ferm_input_list` for more
+# details.
 ferm_input_list: []
+
+
+# .. envvar:: ferm_input_group_list
+#
+# List of iptables INPUT rules to manage for a host group. See
+# :ref:`ferm_input_list` for more details.
 ferm_input_group_list: []
+
+
+# .. envvar:: ferm_input_host_list
+#
+# List of iptables INPUT rules to manage for an individual host. See
+# :ref:`ferm_input_list` for more details.
 ferm_input_host_list: []
+
+
+# .. envvar:: ferm_input_dependent_list
+#
+# List of iptables INPUT rules to manage in dependency to other rules. See
+# :ref:`ferm_input_list` for more details.
 ferm_input_dependent_list: []
 
-  #- type: ''             # name of template file to use, required
-                          #   format: <type>.conf.j2
-  #  name: ''             # custom name used in rule filename, optional
-  #  dport: []            # list of destination ports to manage, required
-  #  weight: '10'         # helps with file sorting in rule directory, optional
-  #  filename: ''         # custom filename instead of a generated one, optional
-  #  delete: False/True   # delete specified rule file, optional
 
+# .. envvar:: ferm_default_weight
+#
 # Set the default rule weight for rules that do not specify it.
 ferm_default_weight: '50'
 
+
+# .. envvar:: ferm_weight_map
+#
 # Dictionary with mapping between "rule classes" and their desired weight.
 ferm_weight_map:
   'loopback': '00'
@@ -144,6 +306,9 @@ ferm_weight_map:
   'any-service': '50'
   'any-reject': '99'
 
+
+# .. envvar:: ferm__default_rules
+#
 # List of default firewall rules defined on each host
 ferm__default_rules: '{{ ferm_rules_default_policy +
                         ferm_rules_log +
@@ -161,6 +326,9 @@ ferm__default_rules: '{{ ferm_rules_default_policy +
                         ferm_rules_fail2ban +
                         ferm_rules_forward }}'
 
+
+# .. envvar:: ferm_rules_default_policy
+#
 # Configure default policies for built-in iptables chains
 ferm_rules_default_policy:
 
@@ -182,6 +350,9 @@ ferm_rules_default_policy:
     name: 'filter_output'
     policy: '{{ ferm_default_policy_output }}'
 
+
+# .. envvar:: ferm_rules_hooks
+#
 # Implement custom firewall hooks
 ferm_rules_hooks:
 
@@ -194,6 +365,9 @@ ferm_rules_hooks:
       @hook post  "run-parts /etc/ferm/hooks/post.d";
       @hook flush "run-parts /etc/ferm/hooks/flush.d";
 
+
+# .. envvar:: ferm_rules_variables
+#
 # Provide custom variables in the firewall configuration
 ferm_rules_variables:
 
@@ -206,6 +380,9 @@ ferm_rules_variables:
       @def $ipv4_enabled = {{ "1" if "ip"  in ferm_domains else "0" }};
       @def $ipv6_enabled = {{ "1" if "ip6" in ferm_domains else "0" }};
 
+
+# .. envvar:: ferm_rules_log
+#
 # Create custom log function which is used by other firewall rules to log
 # packets.
 ferm_rules_log:
@@ -223,6 +400,9 @@ ferm_rules_log:
               {{ ferm_log_target }};
       }
 
+
+# .. envvar:: ferm_rules_filter_loopback
+#
 # Allow connections from localhost
 ferm_rules_filter_loopback:
 
@@ -232,6 +412,9 @@ ferm_rules_filter_loopback:
     name: 'loopback'
     interface: 'lo'
 
+
+# .. envvar:: ferm_rules_filter_ansible_controller
+#
 # Allow connections from Ansible Controllers
 ferm_rules_filter_ansible_controller:
 
@@ -244,6 +427,9 @@ ferm_rules_filter_ansible_controller:
     multiport: True
     accept_any: False
 
+
+# .. envvar:: ferm_rules_filter_icmp
+#
 # Filter ICMP packets
 ferm_rules_filter_icmp:
 
@@ -259,6 +445,9 @@ ferm_rules_filter_icmp:
     hashlimit_target: 'ACCEPT'
     target: 'REJECT'
 
+
+# .. envvar:: ferm_rules_filter_conntrack
+#
 # Enable connection tracking for incoming, forwarded and outgoing traffic.
 ferm_rules_filter_conntrack:
 
@@ -267,6 +456,9 @@ ferm_rules_filter_conntrack:
     weight_class: 'conntrack'
     chain: [ 'INPUT', 'OUTPUT', 'FORWARD' ]
 
+
+# .. envvar:: ferm_rules_filter_syn
+#
 # Filter TCP SYN packets
 ferm_rules_filter_syn:
 
@@ -283,6 +475,9 @@ ferm_rules_filter_syn:
     hashlimit_target: 'RETURN'
     target: 'REJECT'
 
+
+# .. envvar:: ferm_rules_filter_recent_badguys
+#
 # Block all packets marked as "badguys" later in the firewall
 ferm_rules_filter_recent_badguys:
 
@@ -307,6 +502,9 @@ ferm_rules_filter_recent_badguys:
     recent_remove: True
     recent_log: False
 
+
+# .. envvar:: ferm_rules_filter_include_legacy
+#
 # Include rules from legacy ferm directory
 ferm_rules_filter_include_legacy:
 
@@ -328,6 +526,9 @@ ferm_rules_filter_include_legacy:
     when: '{{ ferm_include_legacy | bool }}'
     delete: '{{ not ferm_include_legacy | bool }}'
 
+
+# .. envvar:: ferm_rules_filter_recent_scanners
+#
 # Block potential port scanners that try to access closed ports
 ferm_rules_filter_recent_scanners:
 
@@ -339,6 +540,9 @@ ferm_rules_filter_recent_scanners:
     when: '{{ ferm_mark_portscan | bool }}'
     delete: '{{ not ferm_mark_portscan | bool }}'
 
+
+# .. envvar:: ferm_rules_filter_reject_all
+#
 # Reject all incoming packets not handled by previous rules
 ferm_rules_filter_reject_all:
 
@@ -346,6 +550,9 @@ ferm_rules_filter_reject_all:
     weight: '99'
     weight_class: 'any-reject'
 
+
+# .. envvar:: ferm_rules_fail2ban
+#
 # fail2ban support rules for ferm
 ferm_rules_fail2ban:
 
@@ -355,6 +562,9 @@ ferm_rules_fail2ban:
     when: '{{ ferm_fail2ban | bool }}'
     delete: '{{ not ferm_fail2ban | bool }}'
 
+
+# .. envvar:: ferm_rules_forward
+#
 # Manage packet forwarding to other hosts/containers
 ferm_rules_forward:
 
@@ -407,12 +617,29 @@ ferm_rules_forward:
                    (ansible_local.ferm.forward is undefined or
                     not ansible_local.ferm.forward | bool)))) }}'
 
+
+# .. envvar:: ferm_custom_files
+#
 # Copy or install custom files needed by the firewall, usually scripts. The
 # syntax is the same as used by the ``copy`` Ansible module.
 ferm_custom_files: []
+
+
+# .. envvar:: ferm_group_custom_files
+#
+# Copy or install custom files needed by the firewall host group configuration
 ferm_group_custom_files: []
+
+
+# .. envvar:: ferm_host_custom_files
+#
+# Copy or install custom files needed by the firewall individual host
+# configuration
 ferm_host_custom_files: []
 
+
+# .. envvar:: ferm_fail2ban
+#
 # Enable or disable ``fail2ban`` integration. ``ferm`` will send ``fail2ban`` a reload
 # command after its own configuration is reloaded. If ``fail2ban`` is not present
 # or turned off, nothing will happen.
@@ -427,12 +654,17 @@ ferm_fail2ban: True
 ferm__forward: False
 
 
+# .. envvar:: ferm_external_interfaces
+#
 # List of interfaces that are connected to external network, traffic on these
 # interfaces will be forwarded to all hosts
 ferm_external_interfaces:
   - '{{ ansible_default_ipv4.interface | default("") }}'
   - '{{ ansible_default_ipv6.interface | default("") }}'
 
+
+# .. envvar:: ferm_internal_interfaces
+#
 # List of interfaces that are connected to internal network, traffic on these
 # interfaces will be forwarded only between hosts on that network
 ferm_internal_interfaces: [ 'br1' ]
diff --git a/docs/changelog.rst b/docs/changelog.rst
new file mode 100644
index 0000000..d9e113e
--- /dev/null
+++ b/docs/changelog.rst
@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst
diff --git a/docs/copyright.rst b/docs/copyright.rst
new file mode 100644
index 0000000..3f7c8bd
--- /dev/null
+++ b/docs/copyright.rst
@@ -0,0 +1,20 @@
+Copyright
+=========
+
+::
+
+    Copyright (C) 2016 Maciej Delmanowski <drybjed@gmail.com>
+    Copyright (C) 2016 DebOps Project http://debops.org/
+    [see Credits for more details]
+
+    his program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+    General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program. If not, see http://www.gnu.org/licenses/
diff --git a/docs/credits.rst b/docs/credits.rst
new file mode 100644
index 0000000..7b8a0d7
--- /dev/null
+++ b/docs/credits.rst
@@ -0,0 +1,8 @@
+Credits
+=======
+
+* Maciej Delmanowski <drybjed_at_gmail.com>
+
+  * creator of the DebOps Project
+
+  * current project maintainer
diff --git a/docs/defaults-configuration.rst b/docs/defaults-configuration.rst
new file mode 100644
index 0000000..042f5ac
--- /dev/null
+++ b/docs/defaults-configuration.rst
@@ -0,0 +1,42 @@
+Default variables: configuration
+================================
+
+Some of ``debops.ferm`` default variables have more extensive configuration
+than simple strings or lists, here you can find documentation and examples for
+them.
+
+.. contents::
+   :local:
+      :depth: 1
+
+   .. _ferm_input_list:
+
+ferm_input_list
+---------------
+
+List of ferm INPUT rules that should be present or absent in the firewall rule
+set. The same format is also used for ``ferm_input_group_list``,
+``ferm_input_host_list`` and ``ferm_input_dependent_list``. Each rule is
+defined as a YAML dict with the following keys:
+
+``type``
+  Name of template file to use, required. Format: ``<type>.conf.j2``
+
+``dport``
+  List of destination ports to manage, required.
+
+``name``
+  Optional. Custom name used in the generated rule filename
+
+``weight``
+  Optional. Helps with file sorting in rule directory
+
+``filename``
+  Optional. Custom filename instead of a generated one
+
+``delete``
+  Optional. Delete specified rule file. Possible values: ``False`` or ``True``
+
+Depending on the choosen type, many additional variables are supported. Please
+check the template files located in the ``templates/etc/ferm/filter-input.d/``
+directory.
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
new file mode 100644
index 0000000..4e9f6ee
--- /dev/null
+++ b/docs/getting-started.rst
@@ -0,0 +1,31 @@
+Getting started
+===============
+
+.. contents::
+   :local:
+
+Example inventory
+-----------------
+
+The ``debops.ferm`` role is part of the default DebOps playbook an run on
+all hosts which are part of the ``[debops_all_hosts]`` group. To use this
+role with DebOps it's therefore enough to add your host to the mentioned
+host group (which most likely it is already)::
+
+    [debops_all_hosts]
+    hostname
+
+Example playbook
+----------------
+
+Here's an example playbook which uses the ``debops.ferm`` role::
+
+
+    ---
+
+    - name: Manage iptables rules with ferm
+      hosts: debops_ferm
+
+      roles:
+        - role: debops.ferm
+          tags: ferm
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..3afb704
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,22 @@
+.. _debops.ferm:
+
+Ansible role: debops.ferm
+=========================
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   installation
+   getting-started
+   defaults
+   defaults-configuration
+   copyright
+   credits
+   changelog
+
+..
+ Local Variables:
+ mode: rst
+ ispell-local-dictionary: "american"
+ End:
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..ae3004e
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,6 @@
+Installation
+============
+
+This role requires at least Ansible ``v1.7.0``. To install it, run::
+
+    ansible-galaxy install debops.ferm
diff --git a/docs/introduction.rst b/docs/introduction.rst
new file mode 100644
index 0000000..a150f4b
--- /dev/null
+++ b/docs/introduction.rst
@@ -0,0 +1,15 @@
+Introduction
+============
+
+`ferm`_ is a wrapper around ``iptables`` and ``ip6tables`` commands which lets
+you manage host firewall in an easy and Ansible-friendly way. This role can
+be used to setup firewall rules directly from inventory, or it can be used
+as a dependency by other roles to setup firewall rules for other services.
+
+.. _ferm: http://ferm.foo-projects.org/
+
+..
+ Local Variables:
+ mode: rst
+ ispell-local-dictionary: "american"
+ End: