preliminary privlege escalation unification + pbrun

- become constants inherit existing sudo/su ones
- become command line options, marked sudo/su as deprecated and moved sudo/su passwords to runas group
- changed method signatures as privlege escalation is collapsed to become
- added tests for su and become, diabled su for lack of support in local.py
- updated playbook,play and task objects to become
- added become to runner
- added whoami test for become/sudo/su
- added home override dir for plugins
- removed useless method from ask pass
- forced become pass to always be string also uses to_bytes
- fixed fakerunner for tests
- corrected reference in synchronize action plugin
- added pfexec (needs testing)
- removed unused sudo/su in runner init
- removed deprecated info
- updated pe tests to allow to run under sudo and not need root
- normalized become options into a funciton to avoid duplication and inconsistencies
- pushed suppored list to connection classs property
- updated all connection plugins to latest 'become' pe

- includes fixes from feedback (including typos)
- added draft docs
- stub of become_exe, leaving for future v2 fixes

13 files changed, 182 insertions, 4 deletions

diff --git a/test/integration/destructive.yml b/test/integration/destructive.yml
index 4720319482..54c905bdf6 100644
--- a/test/integration/destructive.yml
+++ b/test/integration/destructive.yml
@@ -3,6 +3,8 @@
   roles:
     # In destructive because it creates and removes a user
     - { role: test_sudo, tags: test_sudo}
+    #- { role: test_su, tags: test_su} # wait till su support is added to local connection, needs tty
+    - { role: test_become, tags: test_become}
     - { role: test_service, tags: test_service }
     # Current pip unconditionally uses md5.  We can re-enable if pip switches
     # to a different hash or allows us to not check md5
diff --git a/test/integration/roles/test_become/files/baz.txt b/test/integration/roles/test_become/files/baz.txt
new file mode 100644
index 0000000000..b8d834daa4
--- /dev/null
+++ b/test/integration/roles/test_become/files/baz.txt
@@ -0,0 +1 @@
+testing tilde expansion with become
diff --git a/test/integration/roles/test_become/tasks/main.yml b/test/integration/roles/test_become/tasks/main.yml
new file mode 100644
index 0000000000..1b00759645
--- /dev/null
+++ b/test/integration/roles/test_become/tasks/main.yml
@@ -0,0 +1,77 @@
+- include_vars: default.yml
+
+- name: Create test user
+  become: True
+  become_user: root
+  user:
+    name: "{{ become_test_user }}"
+
+- name: test becoming user
+  shell: whoami
+  become: True
+  become_user: "{{ become_test_user }}"
+  register: results
+
+- assert:
+    that:
+      - "results.stdout == '{{ become_test_user }}'"
+
+- name: tilde expansion honors become in file
+  become: True
+  become_user: "{{ become_test_user }}"
+  file:
+    path: "~/foo.txt"
+    state: touch
+
+- name: check that the path in the user's home dir was created
+  stat:
+    path: "~{{ become_test_user }}/foo.txt"
+  register: results
+
+- assert:
+    that:
+      - "results.stat.exists == True"
+      - "results.stat.path|dirname|basename == '{{ become_test_user }}'"
+
+- name: tilde expansion honors become in template
+  become: True
+  become_user: "{{ become_test_user }}"
+  template:
+    src: "bar.j2"
+    dest: "~/bar.txt"
+
+- name: check that the path in the user's home dir was created
+  stat:
+    path: "~{{ become_test_user }}/bar.txt"
+  register: results
+
+- assert:
+    that:
+      - "results.stat.exists == True"
+      - "results.stat.path|dirname|basename == '{{ become_test_user }}'"
+
+- name: tilde expansion honors become in copy
+  become: True
+  become_user: "{{ become_test_user }}"
+  copy:
+    src: baz.txt
+    dest: "~/baz.txt"
+
+- name: check that the path in the user's home dir was created
+  stat:
+    path: "~{{ become_test_user }}/baz.txt"
+  register: results
+
+- assert:
+    that:
+      - "results.stat.exists == True"
+      - "results.stat.path|dirname|basename == '{{ become_test_user }}'"
+
+- name: Remove test user and their home dir
+  become: True
+  become_user: root
+  user:
+    name: "{{ become_test_user }}"
+    state: "absent"
+    remove: "yes"
+
diff --git a/test/integration/roles/test_become/templates/bar.j2 b/test/integration/roles/test_become/templates/bar.j2
new file mode 100644
index 0000000000..7c5fe0ab49
--- /dev/null
+++ b/test/integration/roles/test_become/templates/bar.j2
@@ -0,0 +1 @@
+{{ become_test_user }}
diff --git a/test/integration/roles/test_become/vars/default.yml b/test/integration/roles/test_become/vars/default.yml
new file mode 100644
index 0000000000..223d44ed24
--- /dev/null
+++ b/test/integration/roles/test_become/vars/default.yml
@@ -0,0 +1 @@
+become_test_user: ansibletest1
diff --git a/test/integration/roles/test_su/files/baz.txt b/test/integration/roles/test_su/files/baz.txt
new file mode 100644
index 0000000000..7e677748a2
--- /dev/null
+++ b/test/integration/roles/test_su/files/baz.txt
@@ -0,0 +1 @@
+testing tilde expansion with su
diff --git a/test/integration/roles/test_su/tasks/main.yml b/test/integration/roles/test_su/tasks/main.yml
new file mode 100644
index 0000000000..65e9b2306f
--- /dev/null
+++ b/test/integration/roles/test_su/tasks/main.yml
@@ -0,0 +1,75 @@
+- include_vars: default.yml
+
+- name: Create test user
+  su: True
+  user:
+    name: "{{ su_test_user }}"
+
+- name: test becoming user
+  shell: whoami
+  su: True
+  su_user: "{{ su_test_user }}"
+  register: results
+
+- assert:
+    that:
+      - "results.stdout == '{{ su_test_user }}'"
+
+- name: tilde expansion honors su in file
+  su: True
+  su_user: "{{ su_test_user }}"
+  file:
+    path: "~/foo.txt"
+    state: touch
+
+- name: check that the path in the user's home dir was created
+  stat:
+    path: "~{{ su_test_user }}/foo.txt"
+  register: results
+
+- assert:
+    that:
+      - "results.stat.exists == True"
+      - "results.stat.path|dirname|basename == '{{ su_test_user }}'"
+
+- name: tilde expansion honors su in template
+  su: True
+  su_user: "{{ su_test_user }}"
+  template:
+    src: "bar.j2"
+    dest: "~/bar.txt"
+
+- name: check that the path in the user's home dir was created
+  stat:
+    path: "~{{ su_test_user }}/bar.txt"
+  register: results
+
+- assert:
+    that:
+      - "results.stat.exists == True"
+      - "results.stat.path|dirname|basename == '{{ su_test_user }}'"
+
+- name: tilde expansion honors su in copy
+  su: True
+  su_user: "{{ su_test_user }}"
+  copy:
+    src: baz.txt
+    dest: "~/baz.txt"
+
+- name: check that the path in the user's home dir was created
+  stat:
+    path: "~{{ su_test_user }}/baz.txt"
+  register: results
+
+- assert:
+    that:
+      - "results.stat.exists == True"
+      - "results.stat.path|dirname|basename == '{{ su_test_user }}'"
+
+- name: Remove test user and their home dir
+  su: True
+  user:
+    name: "{{ su_test_user }}"
+    state: "absent"
+    remove: "yes"
+
diff --git a/test/integration/roles/test_su/templates/bar.j2 b/test/integration/roles/test_su/templates/bar.j2
new file mode 100644
index 0000000000..0f420227e0
--- /dev/null
+++ b/test/integration/roles/test_su/templates/bar.j2
@@ -0,0 +1 @@
+{{ su_test_user }}
diff --git a/test/integration/roles/test_su/vars/default.yml b/test/integration/roles/test_su/vars/default.yml
new file mode 100644
index 0000000000..bb0da6b25d
--- /dev/null
+++ b/test/integration/roles/test_su/vars/default.yml
@@ -0,0 +1 @@
+su_test_user: ansibletest1
diff --git a/test/integration/roles/test_sudo/tasks/main.yml b/test/integration/roles/test_sudo/tasks/main.yml
index 022e7d7422..372f175d29 100644
--- a/test/integration/roles/test_sudo/tasks/main.yml
+++ b/test/integration/roles/test_sudo/tasks/main.yml
@@ -1,9 +1,20 @@
 - include_vars: default.yml
 
 - name: Create test user
+  sudo: true
   user:
     name: "{{ sudo_test_user }}"
 
+- name: test becoming user
+  shell: whoami
+  sudo: True
+  sudo_user: "{{ sudo_test_user }}"
+  register: results
+
+- assert:
+    that:
+      - "results.stdout == '{{ sudo_test_user }}'"
+
 - name: tilde expansion honors sudo in file
   sudo: True
   sudo_user: "{{ sudo_test_user }}"
@@ -56,6 +67,7 @@
       - "results.stat.path|dirname|basename == '{{ sudo_test_user }}'"
 
 - name: Remove test user and their home dir
+  sudo: true
   user:
     name: "{{ sudo_test_user }}"
     state: "absent"
diff --git a/test/units/TestPlayVarsFiles.py b/test/units/TestPlayVarsFiles.py
index f241936a12..497c3112ed 100644
--- a/test/units/TestPlayVarsFiles.py
+++ b/test/units/TestPlayVarsFiles.py
@@ -41,6 +41,9 @@ class FakePlayBook(object):
         self.sudo_user = None
         self.su = None
         self.su_user = None
+        self.become  = None
+        self.become_method  = None
+        self.become_user = None
         self.transport = None
         self.only_tags = None
         self.skip_tags = None
diff --git a/test/units/TestSynchronize.py b/test/units/TestSynchronize.py
index be8a8af129..d8a85e20e7 100644
--- a/test/units/TestSynchronize.py
+++ b/test/units/TestSynchronize.py
@@ -18,6 +18,9 @@ class FakeRunner(object):
         self.remote_user = None
         self.private_key_file = None
         self.check = False
+        self.become = False
+        self.become_method = False
+        self.become_user = False
 
     def _execute_module(self, conn, tmp, module_name, args,
         async_jid=None, async_module=None, async_limit=None, inject=None, 
@@ -76,7 +79,7 @@ class TestSynchronize(unittest.TestCase):
         """ verify the synchronize action plugin unsets and then sets sudo """ 
 
         runner = FakeRunner()
-        runner.sudo = True
+        runner.become = True
         runner.remote_user = "root"
         runner.transport = "ssh"
         conn = FakeConn()
@@ -97,7 +100,7 @@ class TestSynchronize(unittest.TestCase):
         assert runner.executed_complex_args == {'dest':'root@el6.lab.net:/tmp/bar',
                                                 'src':'/tmp/foo',
                                                 'rsync_path':'"sudo rsync"'}, "wrong args used"
-        assert runner.sudo == True, "sudo was not reset to True" 
+        assert runner.become == True, "sudo was not reset to True"
 
 
     def test_synchronize_action_local(self):
diff --git a/test/units/TestUtils.py b/test/units/TestUtils.py
index 0ba1586cda..c0ca9ba538 100644
--- a/test/units/TestUtils.py
+++ b/test/units/TestUtils.py
@@ -498,7 +498,7 @@ class TestUtils(unittest.TestCase):
         self.assertEqual(len(cmd), 3)
         self.assertTrue('-u root' in cmd[0])
         self.assertTrue('-p "[sudo via ansible, key=' in cmd[0] and cmd[1].startswith('[sudo via ansible, key'))
-        self.assertTrue('echo SUDO-SUCCESS-' in cmd[0] and cmd[2].startswith('SUDO-SUCCESS-'))
+        self.assertTrue('echo BECOME-SUCCESS-' in cmd[0] and cmd[2].startswith('BECOME-SUCCESS-'))
         self.assertTrue('sudo -k' in cmd[0])
 
     def test_make_su_cmd(self):
@@ -506,7 +506,7 @@ class TestUtils(unittest.TestCase):
         self.assertTrue(isinstance(cmd, tuple))
         self.assertEqual(len(cmd), 3)
         self.assertTrue('root -c "/bin/sh' in cmd[0] or ' root -c /bin/sh' in cmd[0])
-        self.assertTrue('echo SUDO-SUCCESS-' in cmd[0] and cmd[2].startswith('SUDO-SUCCESS-'))
+        self.assertTrue('echo BECOME-SUCCESS-' in cmd[0] and cmd[2].startswith('BECOME-SUCCESS-'))
 
     def test_to_unicode(self):
         uni = ansible.utils.unicode.to_unicode(u'ansible')