Documentation

.gitignore

@@ -5,3 +5,4 @@ inventory
 plugins
 roles
 todo
+wiki

README.md

@@ -78,3 +78,35 @@ sudo ln -s /opt/ansible/directory/ansible.sh a
 sudo ln -s /opt/ansible/directory/ansible-playbook.sh apb
 sudo ln -s /opt/ansible/directory/sanity.sh asanity
 ```
+
+### Preparing access to existing hosts
+
+Ansible knows the hosts by name and the company specific naming convention should
+be reflected on each local host that wants to use Ansible to manage them. You'll
+find the hostnames in the file called ```inventory``` and you should make sure
+that your local host knows them by name and their IP address. For this, add a new
+line for each of those hosts into your ```/etc/hosts``` file starting with the
+IP address followed by a space and the hostname from the inventory file.
+
+Next, and this is the final piece before you can start using Ansible to access
+your hosts, make sure that you can access your hosts via SSH. This repository
+is built with security at the forefront and therefore access is only available
+through a PKI infrastructure. To configure your system for easy access, you
+should have a file ```$HOME/.ssh/config``` with some content similar to the
+following:
+
+```
+ForwardAgent yes
+
+Host *
+  User [YOUR REMOTE USERNAME]
+  IdentityFile ~/.ssh/id_rsa
+```
+
+The above setting applies to all hosts and the definition of the remote user name
+is only neccessary if that remote username is different from your local one. Please
+note that you should define the same username also in ```$HOME/.ansible.cfg```
+
+## Where to go next?
+
+The best place to continue reading is by heading over to the [Wiki][wikis/home]