Issue #538 - added unix-ls command (#682)

* Issue #538 - added unix-ls command

Updated file:
f5/bigip/tm/util/__init__.py

Added file:
f5/bigip/tm/util/Unix_Ls.py
f5/bigip/tm/util/test/test_unix_ls.py
test/function/tm/util/test_unix_ls.py

* Issue #538 - fixed/expanded test cases

* Issue #538 - add tmos version dependency to test case

* Issue #538 - fixed incorrect references in header

Author: f5-rahm

f5/bigip/tm/util/Unix_Ls.py

@@ -0,0 +1,58 @@
+# coding=utf-8
+#
+# Copyright 2016 F5 Networks Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""BIG-IP® utility module
+
+REST URI
+    ``http://localhost/mgmt/tm/util/unix-ls``
+
+GUI Path
+    N/A
+
+REST Kind
+    ``tm:util:unix-ls:*``
+"""
+
+from f5.bigip.mixins import CommandExecutionMixin
+from f5.bigip.resource import UnnamedResource
+from f5.utils.util_exceptions import UtilError
+
+
+class Unix_Ls(UnnamedResource, CommandExecutionMixin):
+
+    def __init__(self, util):
+        super(Unix_Ls, self).__init__(util)
+        self._meta_data['required_command_parameters'].update(('utilCmdArgs',))
+        self._meta_data['required_json_kind'] = 'tm:util:unix-ls:runstate'
+        self._meta_data['allowed_commands'].append('run')
+
+    def _exec_cmd(self, command, **kwargs):
+        kwargs['command'] = command
+        self._check_exclusive_parameters(**kwargs)
+        requests_params = self._handle_requests_params(kwargs)
+        self._check_command_parameters(**kwargs)
+        session = self._meta_data['bigip']._meta_data['icr_session']
+        response = session.post(
+            self._meta_data['uri'], json=kwargs, **requests_params)
+        self._local_update(response.json())
+
+        if 'commandResult' in self.__dict__:
+            if self.commandResult.startswith('/bin/ls'):
+                raise UtilError('%s' % self.commandResult.split(' ', 1)[1])
+            else:
+                return self
+        else:
+            return self

f5/bigip/tm/util/__init__.py

@@ -28,6 +28,7 @@
 """
 
 from f5.bigip.resource import PathElement
+from f5.bigip.tm.util.Unix_Ls import Unix_Ls
 from f5.bigip.tm.util.Unix_Mv import Unix_Mv
 from f5.bigip.tm.util.Unix_Rm import Unix_Rm
 
@@ -36,6 +37,7 @@ class Util(PathElement):
     def __init__(self, bigip):
         super(Util, self).__init__(bigip)
         self._meta_data['allowed_lazy_attributes'] = [
+            Unix_Ls,
             Unix_Mv,
             Unix_Rm
         ]

f5/bigip/tm/util/test/test_unix_ls.py

@@ -0,0 +1,47 @@
+# Copyright 2016 F5 Networks Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import mock
+import pytest
+
+from f5.bigip import ManagementRoot
+from f5.bigip.tm.util.Unix_Ls import Unix_Ls
+
+
+@pytest.fixture
+def FakeUnixLs():
+    fake_sys = mock.MagicMock()
+    fake_ls = Unix_Ls(fake_sys)
+    return fake_ls
+
+
+@pytest.fixture
+def FakeiControl(fakeicontrolsession):
+    mr = ManagementRoot('host', 'fake_admin', 'fake_admin')
+    mock_session = mock.MagicMock()
+    mock_session.post.return_value.json.return_value = {}
+    mr._meta_data['icr_session'] = mock_session
+    return mr.tm.util.unix_ls
+
+
+class TestUnixLsCommand(object):
+    def test_command_unix_ls(self, FakeiControl):
+        FakeiControl.exec_cmd('run',
+                              utilCmdArgs='-als /var/tmp/')
+        session = FakeiControl._meta_data['bigip']._meta_data['icr_session']
+        assert session.post.call_args == mock.call(
+            'https://host:443/mgmt/tm/util/unix-ls/',
+            json={'utilCmdArgs': '-als /var/tmp/', 'command': 'run'}
+        )

test/functional/tm/util/test_unix_ls.py

@@ -0,0 +1,69 @@
+
+# Copyright 2016 F5 Networks Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from distutils.version import LooseVersion
+import pytest
+
+from f5.utils.util_exceptions import UtilError
+from icontrol.session import iControlUnexpectedHTTPError
+import os
+from tempfile import NamedTemporaryFile
+
+
+def test_E_unix_ls(mgmt_root):
+    ntf = NamedTemporaryFile(delete=False)
+    ntf_basename = os.path.basename(ntf.name)
+    ntf.write('text for test file')
+    ntf.seek(0)
+    mgmt_root.shared.file_transfer.uploads.upload_file(ntf.name)
+    tpath_name = '/var/config/rest/downloads/{0}'.format(ntf_basename)
+
+    # create
+    fls1 = mgmt_root.tm.util.unix_ls.exec_cmd('run', utilCmdArgs=tpath_name)
+    # grab tmos version for later use in version discrepancy
+    tmos_ver = fls1._meta_data['bigip']._meta_data['tmos_version']
+
+    # validate object was created
+    assert fls1.utilCmdArgs == tpath_name
+
+    # commandResult should be present with successful listing
+    assert 'commandResult' in fls1.__dict__
+
+    # commandResult listing should match the file we requested a listing for
+    assert '{0}\n'.format(fls1.utilCmdArgs) == fls1.commandResult
+
+    # UtilError should be raised when non-existent file is mentioned
+    with pytest.raises(UtilError) as err:
+        mgmt_root.tm.util.unix_ls.exec_cmd('run',
+                                           utilCmdArgs='/configs/testfile.txt')
+        assert 'No such file or directory' in err.response.text
+
+    # clean up created file
+    mgmt_root.tm.util.unix_rm.exec_cmd('run', utilCmdArgs=tpath_name)
+
+    # test that a bad command option errors out
+    if LooseVersion(tmos_ver) < LooseVersion('12.0.0'):
+        with pytest.raises(UtilError) as err:
+            mgmt_root.tm.util.unix_ls.exec_cmd('run',
+                                               utilCmdArgs='-9')
+            assert 'invalid option -- 9' in err.response.text
+
+    else:
+        with pytest.raises(iControlUnexpectedHTTPError) as err:
+            mgmt_root.tm.util.unix_ls.exec_cmd('run',
+                                               utilCmdArgs='-9')
+            assert err.response.status_code == 400
+            assert 'unix-ls does not support' in err.response.text