diff --git a/roles/network/README.md b/roles/network/README.md
new file mode 100644
index 0000000..0b61fb9
--- /dev/null
+++ b/roles/network/README.md
@@ -0,0 +1,27 @@
+## Ansible role: network
+
+### VIP interfaces
+
+VIP (virtual IP address) are defined using nework_vip_interfaces variable.
+Implementation is operating system specific itself. Currently OpenBSD uses
+CARP (Command Address Redundancy Protocol) and Linux uses VRRP (Virtual
+Router Redundancy Protocol) with keepalived daemon.
+
+Parameters:
+
+ * device: physical network device
+ * vhid: router/host ID
+ * ipaddr: virtual ip address
+ * netmask: netmask for virtual ip address (optional on Linux)
+ * pass: password for auththenticating advertisements
+ * priority: used for elections higher value is preferred master
+   value can be between 0 and 240 (optional)
+
+Example:
+
+network_vip_interfaces:
+  - device: eth0
+  - vhid: 1
+  - ipaddr: 192.0.2.1
+  - netmask: 255.255.255.0
+  - pass: secret