docs+man: Introduce docs and manpage for remote plugin.

Introduce the documentation regarding the new remote plugin.
Include information about using the remote plugin in the manual page.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

docs/source/RemoteMachinePlugin.rst

+.. _Remote Machine Plugin:
+
+=====================
+Remote Machine Plugin
+=====================
+
+Avocado implements a feature that lets
+you run tests directly in a remote machine with SSH connection,
+provided that you properly set it up by installing Avocado in it.
+
+Remote Plugin Basics
+====================
+
+The remote plugin is one of the basic plugins provided by Avocado.
+You can check for its presence by listing your plugins::
+
+    $ scripts/avocado plugins
+    Plugins loaded:
+        ...
+        run_remote - Run tests on a remote machine (Enabled)
+        ...
+
+This plugin adds a number of options to the avocado test runner::
+
+      --remote-hostname REMOTE_HOSTNAME
+                            Specify the hostname to login on remote machine
+      --remote-port REMOTE_PORT
+                            Specify the port number to login on remote machine.
+                            Default: 22
+      --remote-username REMOTE_USERNAME
+                            Specify the username to login on remote machine
+      --remote-password REMOTE_PASSWORD
+                            Specify the password to login on remote machine
+
+From these options, you are normally going to use `--remote-hostname` and
+`--remote-username` in case you did set up your VM with password-less
+SSH connection (through SSH keys).
+
+Remote Setup
+============
+
+Make sure you have:
+
+ 1) Avocado RPM installed. You can see more info on
+    how to do that in the Getting Started Guide.
+ 2) The domain IP address or fully qualified hostname and the port number.
+ 3) All pre-requesites for your test to run installed inside the remote machine
+    (gcc, make and others if you want to compile a 3rd party test suite written
+    in C, for example).
+ 4) Optionally, you may have password less SSH login on your remote machine enabled.
+
+
+Running your test
+=================
+
+Once everything is verified and covered, you may run your test. Example::
+
+    $ scripts/avocado run --remote-hostname 192.168.122.30 --remote-username fedora examples/tests/sleeptest.py examples/tests/failtest.py
+    REMOTE LOGIN  : fedora@192.168.122.30:22
+    JOB ID    : 60ddd718e7d7bb679f258920ce3c39ce73cb9779
+    JOB LOG   : /home/rmoura/avocado/job-results/job-2014-10-23T11.45-a329461/job.log
+    TESTS     : 2
+    (1/2) examples/tests/sleeptest.py: PASS (1.00 s)
+    (2/2) examples/tests/failtest.py: FAIL (0.00 s)
+    PASS      : 1
+    ERROR     : 0
+    NOT FOUND : 0
+    FAIL      : 1
+    SKIP      : 0
+    WARN      : 0
+    TIME      : 1.01 s
+
+As you can see, avocado will copy the tests you have to your remote machine and
+execute them. A bit of extra logging information is added to your job summary,
+mainly to distinguish the regular execution from the remote one. Note here that
+we did not need `--remote-password` because the SSH key is already setup.

docs/source/index.rst

@@ -21,6 +21,7 @@ Contents:
    Plugins
    OutputPlugins
    VirtualMachinePlugin
+   RemoteMachinePlugin
    DebuggingWithGDB
    ContributionGuide
    api/modules

man/avocado.rst

@@ -378,6 +378,42 @@ Let's look what's in each of them::
 Now, every time this test runs, it'll take into account the expected files that
 were recorded, no need to do anything else but run the test.
 
+RUNNING REMOTE TESTS
+====================
+
+Avocado allows you to execute tests on a remote machine by means of a SSH
+network connection. The remote machine must be configured to accept remote
+connections and the Avocado framework have to be installed in both origin
+and remote machines.
+
+When running tests on remote machine, the test sources and its data (if any present)
+are transfered to the remote target, just before the test execution.
+After the test execution, all test results are transfered back to the origin machine.
+
+Here is how to run the sleeptest example test in a remote machine with IP
+address 192.168.0.123 (standard port 22), remote user name `fedora` and
+remote user password `123456`::
+
+ $ avocado run --remote-hostname 192.168.0.123 --remote-username fedora --remote-password 123456
+
+The output should look like::
+
+ REMOTE LOGIN  : fedora@192.168.0.123:22
+ JOB ID    : <JOBID>
+ JOB LOG   : /home/<user>/avocado/job-results/job-<date>-<shortid>/job.log
+ TESTS     : 1
+ (1/1) sleeptest.py:  PASS (1.01 s)
+ PASS      : 1
+ ERROR     : 0
+ NOT FOUND : 0
+ FAIL      : 0
+ SKIP      : 0
+ WARN      : 0
+ TIME      : 1.01 s
+
+For more information, please consult the topic Remote Machine Plugin
+on Avocado's online documentation.
+
 FILES
 =====