Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_cifs_acl.py

raw
1 #!/usr/bin/python
2
3 # (c) 2018-2026, NetApp, Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5
6 from __future__ import absolute_import, division, print_function
7 __metaclass__ = type
8
9 DOCUMENTATION = '''
10 author: NetApp Ansible Team (@carchi8py) <[email protected]>
11 short_description: NetApp ONTAP manage cifs-share-access-control
12 description:
13 - "Create or destroy or modify cifs-share-access-controls on ONTAP"
14 extends_documentation_fragment:
15 - netapp.ontap.netapp.na_ontap
16 module: na_ontap_cifs_acl
17 options:
18 permission:
19 choices: ['no_access', 'read', 'change', 'full_control']
20 type: str
21 description:
22 - The access rights that the user or group has on the defined CIFS share.
23 share_name:
24 description:
25 - The name of the cifs-share-access-control to manage.
26 required: true
27 type: str
28 aliases: ['share']
29 state:
30 choices: ['present', 'absent']
31 description:
32 - Whether the specified CIFS share acl should exist or not.
33 default: present
34 type: str
35 vserver:
36 description:
37 - Name of the vserver to use.
38 required: true
39 type: str
40 user_or_group:
41 description:
42 - The user or group name for which the permissions are listed.
43 required: true
44 type: str
45 type:
46 description:
47 - The type (also known as user-group-type) of the user or group to add to the ACL.
48 - Type is required for create, delete and modify unix-user or unix-group to/from the ACL in ZAPI.
49 type: str
50 choices: [windows, unix_user, unix_group]
51 version_added: 21.17.0
52
53 lambda_config:
54 description:
55 - Configuration parameters for AWS Lambda proxy functionality.
56 - These option and suboptions are only supported with REST.
57 type: dict
58 version_added: 23.4.0
59 suboptions:
60 function_name:
61 description:
62 - The name of the AWS Lambda function to invoke.
63 type: str
64 required: true
65 aws_region:
66 description:
67 - The name of the AWS region.
68 type: str
69 required: true
70 aws_profile:
71 description:
72 - The name of the AWS profile to use for authentication.
73 type: str
74
75 notes:
76 - Supports AWS Lambda proxy functionality when using REST. See the README file for examples.
77 '''
78
79 EXAMPLES = """
80 - name: Create CIFS share ACL
81 netapp.ontap.na_ontap_cifs_acl:
82 state: present
83 share_name: cifsShareName
84 user_or_group: Everyone
85 permission: read
86 vserver: "{{ netapp_vserver }}"
87 hostname: "{{ netapp_hostname }}"
88 username: "{{ netapp_username }}"
89 password: "{{ netapp_password }}"
90
91 - name: Modify CIFS share ACL permission
92 netapp.ontap.na_ontap_cifs_acl:
93 state: present
94 share_name: cifsShareName
95 user_or_group: Everyone
96 permission: change
97 vserver: "{{ netapp_vserver }}"
98 hostname: "{{ netapp_hostname }}"
99 username: "{{ netapp_username }}"
100 password: "{{ netapp_password }}"
101
102 - name: Delete CIFS share ACL
103 netapp.ontap.na_ontap_cifs_acl:
104 state: absent
105 share_name: cifsShareName
106 user_or_group: localUser
107 permission: read
108 vserver: "{{ netapp_vserver }}"
109 hostname: "{{ netapp_hostname }}"
110 username: "{{ netapp_username }}"
111 password: "{{ netapp_password }}"
112 """
113
114 RETURN = """
115 """
116
117
118 import traceback
119
120 from ansible.module_utils.basic import AnsibleModule
121 from ansible.module_utils._text import to_native
122 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
123 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
124 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
125 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
126
127
128 class NetAppONTAPCifsAcl:
129 """
130 Methods to create/delete/modify CIFS share/user access-control
131 """
132
133 def __init__(self):
134 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
135 self.argument_spec.update(dict(
136 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
137 vserver=dict(required=True, type='str'),
138 share_name=dict(required=True, type='str', aliases=['share']),
139 user_or_group=dict(required=True, type='str'),
140 permission=dict(required=False, type='str', choices=['no_access', 'read', 'change', 'full_control']),
141 type=dict(required=False, type='str', choices=['windows', 'unix_user', 'unix_group']),
142 ))
143 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
144 self.module = AnsibleModule(
145 argument_spec=self.argument_spec,
146 required_if=[
147 ('state', 'present', ['permission']),
148 ('use_lambda', True, ['lambda_config'])
149 ],
150 supports_check_mode=True
151 )
152 self.na_helper = NetAppModule()
153 self.parameters = self.na_helper.set_parameters(self.module.params)
154 # Set up Rest API
155 self.rest_api = OntapRestAPI(self.module)
156 self.use_rest = self.rest_api.is_rest()
157
158 if not self.use_rest:
159 if self.parameters.get('use_lambda'):
160 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
161 if netapp_utils.has_netapp_lib() is False:
162 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
163 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
164
165 def get_cifs_acl(self):
166 """
167 Return details about the cifs-share-access-control
168 :param:
169 name : Name of the cifs-share-access-control
170 :return: Details about the cifs-share-access-control. None if not found.
171 :rtype: dict
172 """
173 cifs_acl_iter = netapp_utils.zapi.NaElement('cifs-share-access-control-get-iter')
174 cifs_acl_info = netapp_utils.zapi.NaElement('cifs-share-access-control')
175 cifs_acl_info.add_new_child('share', self.parameters['share_name'])
176 cifs_acl_info.add_new_child('user-or-group', self.parameters['user_or_group'])
177 cifs_acl_info.add_new_child('vserver', self.parameters['vserver'])
178 if self.parameters.get('type') is not None:
179 cifs_acl_info.add_new_child('user-group-type', self.parameters['type'])
180 query = netapp_utils.zapi.NaElement('query')
181 query.add_child_elem(cifs_acl_info)
182 cifs_acl_iter.add_child_elem(query)
183 try:
184 result = self.server.invoke_successfully(cifs_acl_iter, True)
185 except netapp_utils.zapi.NaApiError as error:
186 self.module.fail_json(msg='Error getting cifs-share-access-control %s: %s'
187 % (self.parameters['share_name'], to_native(error)))
188 return_value = None
189 # check if query returns the expected cifs-share-access-control
190 if result.get_child_by_name('num-records') and \
191 int(result.get_child_content('num-records')) == 1:
192
193 cifs_acl = result.get_child_by_name('attributes-list').get_child_by_name('cifs-share-access-control')
194 return_value = {
195 'share': cifs_acl.get_child_content('share'),
196 'user-or-group': cifs_acl.get_child_content('user-or-group'),
197 'permission': cifs_acl.get_child_content('permission'),
198 'type': cifs_acl.get_child_content('user-group-type'),
199 }
200 return return_value
201
202 def create_cifs_acl(self):
203 """
204 Create access control for the given CIFS share/user-group
205 """
206 options = {
207 'share': self.parameters['share_name'],
208 'user-or-group': self.parameters['user_or_group'],
209 'permission': self.parameters['permission']
210 }
211 # type is required for unix-user and unix-group
212 if self.parameters.get('type') is not None:
213 options['user-group-type'] = self.parameters['type']
214
215 cifs_acl_create = netapp_utils.zapi.NaElement.create_node_with_children(
216 'cifs-share-access-control-create', **options)
217 try:
218 self.server.invoke_successfully(cifs_acl_create,
219 enable_tunneling=True)
220 except netapp_utils.zapi.NaApiError as error:
221 self.module.fail_json(msg='Error creating cifs-share-access-control %s: %s'
222 % (self.parameters['share_name'], to_native(error)),
223 exception=traceback.format_exc())
224
225 def delete_cifs_acl(self):
226 """
227 Delete access control for the given CIFS share/user-group
228 """
229 options = {
230 'share': self.parameters['share_name'],
231 'user-or-group': self.parameters['user_or_group']
232 }
233 # type is required for unix-user and unix-group
234 if self.parameters.get('type') is not None:
235 options['user-group-type'] = self.parameters['type']
236 cifs_acl_delete = netapp_utils.zapi.NaElement.create_node_with_children(
237 'cifs-share-access-control-delete', **options)
238 try:
239 self.server.invoke_successfully(cifs_acl_delete,
240 enable_tunneling=True)
241 except netapp_utils.zapi.NaApiError as error:
242 self.module.fail_json(msg='Error deleting cifs-share-access-control %s: %s'
243 % (self.parameters['share_name'], to_native(error)),
244 exception=traceback.format_exc())
245
246 def modify_cifs_acl_permission(self):
247 """
248 Change permission or type for the given CIFS share/user-group
249 """
250 options = {
251 'share': self.parameters['share_name'],
252 'user-or-group': self.parameters['user_or_group'],
253 'permission': self.parameters['permission']
254 }
255 # type is required for unix-user and unix-group
256 if self.parameters.get('type') is not None:
257 options['user-group-type'] = self.parameters['type']
258
259 cifs_acl_modify = netapp_utils.zapi.NaElement.create_node_with_children(
260 'cifs-share-access-control-modify', **options)
261 try:
262 self.server.invoke_successfully(cifs_acl_modify,
263 enable_tunneling=True)
264 except netapp_utils.zapi.NaApiError as error:
265 self.module.fail_json(msg='Error modifying cifs-share-access-control permission %s: %s'
266 % (self.parameters['share_name'], to_native(error)),
267 exception=traceback.format_exc())
268
269 def get_modify(self, current):
270
271 modify = self.na_helper.get_modified_attributes(current, self.parameters)
272 if not modify or ('permission' in modify and len(modify) == 1):
273 return modify
274 if 'type' in modify:
275 self.module.fail_json(msg='Error: changing the type is not supported by ONTAP - current: %s, desired: %s'
276 % (current['type'], self.parameters['type']))
277 self.module.fail_json(msg='Error: only permission can be changed - modify: %s' % modify)
278
279 def get_cifs_share_rest(self):
280 """
281 get uuid of the svm which has CIFS share with rest API.
282 """
283 options = {'svm.name': self.parameters.get('vserver'),
284 'name': self.parameters.get('share_name')}
285 api = 'protocols/cifs/shares'
286 fields = 'svm.uuid,name'
287 record, error = rest_generic.get_one_record(self.rest_api, api, options, fields)
288 if error:
289 self.module.fail_json(msg="Error on fetching cifs shares: %s" % error)
290 if record:
291 return {'uuid': record['svm']['uuid']}
292 self.module.fail_json(msg="Error: the cifs share does not exist: %s" % self.parameters['share_name'])
293
294 def get_cifs_acl_rest(self, svm_uuid):
295 """
296 get details of the CIFS share acl with rest API.
297 """
298 if not self.use_rest:
299 return self.get_cifs_acl()
300 query = {'user_or_group': self.parameters.get('user_or_group')}
301 ug_type = self.parameters.get('type')
302 if ug_type:
303 query['type'] = ug_type
304 api = 'protocols/cifs/shares/%s/%s/acls' % (svm_uuid['uuid'], self.parameters.get('share_name'))
305 fields = 'svm.uuid,user_or_group,type,permission'
306 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
307 if error:
308 self.module.fail_json(msg="Error on fetching cifs shares acl: %s" % error)
309 if record:
310 return {
311 'uuid': record['svm']['uuid'],
312 'share': record['share'],
313 'user_or_group': record['user_or_group'],
314 'type': record['type'],
315 'permission': record['permission']
316 }
317 return None
318
319 def create_cifs_acl_rest(self, svm_uuid):
320 """
321 create CIFS share acl with rest API.
322 """
323 if not self.use_rest:
324 return self.create_cifs_acl()
325 body = {
326 'user_or_group': self.parameters.get('user_or_group'),
327 'permission': self.parameters.get('permission')
328 }
329 ug_type = self.parameters.get('type')
330 if ug_type:
331 body['type'] = ug_type
332 api = 'protocols/cifs/shares/%s/%s/acls' % (svm_uuid['uuid'], self.parameters.get('share_name'))
333 dummy, error = rest_generic.post_async(self.rest_api, api, body)
334 if error is not None:
335 self.module.fail_json(msg="Error on creating cifs share acl: %s" % error)
336
337 def delete_cifs_acl_rest(self, current):
338 """
339 Delete access control for the given CIFS share/user-group with rest API.
340 """
341 if not self.use_rest:
342 return self.delete_cifs_acl()
343 body = {'svm.name': self.parameters.get('vserver')}
344 api = 'protocols/cifs/shares/%s/%s/acls/%s/%s' % (
345 current['uuid'], self.parameters.get('share_name'), self.parameters.get('user_or_group'), current.get('type'))
346 dummy, error = rest_generic.delete_async(self.rest_api, api, None, body)
347 if error is not None:
348 self.module.fail_json(msg="Error on deleting cifs share acl: %s" % error)
349
350 def modify_cifs_acl_permission_rest(self, current):
351 """
352 Change permission for the given CIFS share/user-group with rest API.
353 """
354 if not self.use_rest:
355 return self.modify_cifs_acl_permission()
356 body = {'permission': self.parameters.get('permission')}
357 api = 'protocols/cifs/shares/%s/%s/acls/%s/%s' % (
358 current['uuid'], self.parameters.get('share_name'), self.parameters.get('user_or_group'), current.get('type'))
359 dummy, error = rest_generic.patch_async(self.rest_api, api, None, body)
360 if error is not None:
361 self.module.fail_json(msg="Error modifying cifs share ACL permission: %s" % error)
362
363 def apply(self):
364 """
365 Apply action to cifs-share-access-control
366 """
367 svm_uuid = self.get_cifs_share_rest() if self.use_rest else None
368 current = self.get_cifs_acl_rest(svm_uuid)
369 cd_action = self.na_helper.get_cd_action(current, self.parameters)
370 modify = self.get_modify(current) if cd_action is None and self.parameters['state'] == 'present' else None
371 if self.na_helper.changed and not self.module.check_mode:
372 if cd_action == 'create':
373 self.create_cifs_acl_rest(svm_uuid)
374 if cd_action == 'delete':
375 self.delete_cifs_acl_rest(current)
376 if modify:
377 self.modify_cifs_acl_permission_rest(current)
378 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
379 self.module.exit_json(**result)
380
381
382 def main():
383 """
384 Execute action from playbook
385 """
386 cifs_acl = NetAppONTAPCifsAcl()
387 cifs_acl.apply()
388
389
390 if __name__ == '__main__':
391 main()