Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_cifs.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 # import untangle
6
7 '''
8 na_ontap_cifs
9 '''
10
11 from __future__ import absolute_import, division, print_function
12 __metaclass__ = type
13
14 DOCUMENTATION = '''
15 author: NetApp Ansible Team (@carchi8py) <[email protected]>
16 description:
17 - Create or destroy or modify(path) cifs-share on ONTAP.
18 extends_documentation_fragment:
19 - netapp.ontap.netapp.na_ontap
20 module: na_ontap_cifs
21
22 options:
23
24 comment:
25 description:
26 - The CIFS share description.
27 type: str
28 version_added: 21.7.0
29
30 path:
31 description:
32 - The file system path that is shared through this CIFS share. The path is the full, user visible path relative
33 to the vserver root, and it might be crossing junction mount points. The path is in UTF8 and uses forward
34 slash as directory separator.
35 type: str
36
37 vserver:
38 description:
39 - Vserver containing the CIFS share.
40 required: true
41 type: str
42
43 name:
44 description:
45 - The name of the CIFS share. The CIFS share name is a UTF-8 string with the following characters being
46 illegal; control characters from 0x00 to 0x1F, both inclusive, 0x22 (double quotes)
47 required: true
48 aliases: ['share_name']
49 type: str
50
51 share_properties:
52 description:
53 - The list of properties for the CIFS share.
54 - Not supported with REST.
55 - share-properties are separate fields in the REST API.
56 - You can achieve this functionality by setting C(access_based_enumeration), C(change_notify), C(encryption),
57 C(home_directory), C(oplocks), C(show_snapshot), C(continuously_available) and C(namespace_caching).
58 type: list
59 elements: str
60 version_added: 2.8.0
61
62 symlink_properties:
63 description:
64 - The list of symlink properties for this CIFS share.
65 - Not supported with REST, this option is replaced with C(unix_symlink) in REST.
66 type: list
67 elements: str
68 version_added: 2.8.0
69
70 state:
71 choices: ['present', 'absent']
72 description:
73 - Whether the specified CIFS share should exist or not.
74 type: str
75 default: present
76
77 vscan_fileop_profile:
78 choices: ['no_scan', 'standard', 'strict', 'writes_only']
79 description:
80 - Profile_set of file_ops to which vscan on access scanning is applicable.
81 - REST support requires ONTAP 9.15.1 or later.
82 type: str
83 version_added: 2.9.0
84
85 unix_symlink:
86 choices: ['local', 'widelink', 'disable']
87 description:
88 - The list of unix_symlink properties for this CIFS share
89 - This option only supported with REST.
90 type: str
91 version_added: 21.19.0
92
93 access_based_enumeration:
94 description:
95 - If enabled, all folders inside this share are visible to a user based on that individual user access right;
96 prevents the display of folders or other shared resources that the user does not have access to.
97 - This option only supported with REST.
98 type: bool
99 version_added: 22.3.0
100
101 allow_unencrypted_access:
102 description:
103 - Specifies whether or not the SMB2 clients are allowed to access the encrypted share.
104 - This option requires REST and ONTAP 9.11.0 or later.
105 type: bool
106 version_added: 22.3.0
107
108 change_notify:
109 description:
110 - Specifies whether CIFS clients can request for change notifications for directories on this share.
111 - This option only supported with REST.
112 type: bool
113 version_added: 22.3.0
114
115 encryption:
116 description:
117 - Specifies that SMB encryption must be used when accessing this share. Clients that do not support encryption are not
118 able to access this share.
119 - This option only supported with REST.
120 type: bool
121 version_added: 22.3.0
122
123 home_directory:
124 description:
125 - Specifies whether or not the share is a home directory share, where the share and path names are dynamic.
126 - ONTAP home directory functionality automatically offer each user a dynamic share to their home directory without creating an
127 individual SMB share for each user.
128 - This feature enable us to configure a share that maps to different directories based on the user that connects to it
129 - Instead of creating a separate shares for each user, a single share with a home directory parameters can be created.
130 - In a home directory share, ONTAP dynamically generates the share-name and share-path by substituting
131 %w, %u, and %d variables with the corresponding Windows user name, UNIX user name, and domain name, respectively.
132 - This option only supported with REST and cannot modify.
133 type: bool
134 version_added: 22.3.0
135
136 namespace_caching:
137 description:
138 - Specifies whether or not the SMB clients connecting to this share can cache the directory enumeration
139 results returned by the CIFS servers.
140 - This option requires REST and ONTAP 9.10.1 or later.
141 type: bool
142 version_added: 22.3.0
143
144 oplocks:
145 description:
146 - Specify whether opportunistic locks are enabled on this share. "Oplocks" allow clients to lock files and cache content locally,
147 which can increase performance for file operations.
148 - Only supported with REST.
149 type: bool
150 version_added: 22.3.0
151
152 show_snapshot:
153 description:
154 - Specifies whether or not the Snapshot copies can be viewed and traversed by clients.
155 - This option requires REST and ONTAP 9.10.1 or later.
156 type: bool
157 version_added: 22.3.0
158
159 continuously_available :
160 description:
161 - Specifies whether or not the clients connecting to this share can open files in a persistent manner.
162 - Files opened in this way are protected from disruptive events, such as, failover and giveback.
163 - This option requires REST and ONTAP 9.10.1 or later.
164 type: bool
165 version_added: 22.3.0
166
167 browsable:
168 description:
169 - Specifies whether or not the Windows clients can browse the share.
170 - This option requires REST and ONTAP 9.13.1 or later.
171 type: bool
172 version_added: 22.5.0
173
174 show_previous_versions:
175 description:
176 - Specifies that the previous version can be viewed and restored from the client.
177 - This option requires REST and ONTAP 9.13.1 or later.
178 type: bool
179 version_added: 22.5.0
180
181 offline_files:
182 choices: ['none', 'manual', 'documents', 'programs']
183 description:
184 - Allows Windows clients to cache data on this share.
185 - This option is only supported with REST and requires ONTAP 9.10 or later.
186 type: str
187 version_added: 22.11.0
188
189 lambda_config:
190 description:
191 - Configuration parameters for AWS Lambda proxy functionality.
192 - These option and suboptions are only supported with REST.
193 type: dict
194 version_added: 23.4.0
195 suboptions:
196 function_name:
197 description:
198 - The name of the AWS Lambda function to invoke.
199 type: str
200 required: true
201 aws_region:
202 description:
203 - The name of the AWS region.
204 type: str
205 required: true
206 aws_profile:
207 description:
208 - The name of the AWS profile to use for authentication.
209 type: str
210
211 short_description: NetApp ONTAP Manage cifs-share
212 version_added: 2.6.0
213
214 notes:
215 - Supports AWS Lambda proxy functionality when using REST. See README for example usage.
216 '''
217
218 EXAMPLES = """
219 - name: Create CIFS share - ZAPI
220 netapp.ontap.na_ontap_cifs:
221 state: present
222 name: cifsShareName
223 path: /
224 vserver: vserverName
225 share_properties: browsable,oplocks
226 symlink_properties: read_only,enable
227 comment: CIFS share description
228 hostname: "{{ netapp_hostname }}"
229 username: "{{ netapp_username }}"
230 password: "{{ netapp_password }}"
231
232 - name: Delete CIFS share - ZAPI
233 netapp.ontap.na_ontap_cifs:
234 state: absent
235 name: cifsShareName
236 vserver: vserverName
237 hostname: "{{ netapp_hostname }}"
238 username: "{{ netapp_username }}"
239 password: "{{ netapp_password }}"
240
241 - name: Modify path CIFS share - ZAPI
242 netapp.ontap.na_ontap_cifs:
243 state: present
244 name: pb_test
245 vserver: vserverName
246 path: /
247 share_properties: show_previous_versions
248 symlink_properties: disable
249 vscan_fileop_profile: no_scan
250 hostname: "{{ netapp_hostname }}"
251 username: "{{ netapp_username }}"
252 password: "{{ netapp_password }}"
253
254 - name: Create CIFS share - REST
255 netapp.ontap.na_ontap_cifs:
256 state: present
257 name: cifsShareName
258 path: /
259 vserver: vserverName
260 oplocks: true
261 change_notify: true
262 unix_symlink: disable
263 comment: CIFS share description
264 hostname: "{{ netapp_hostname }}"
265 username: "{{ netapp_username }}"
266 password: "{{ netapp_password }}"
267
268 - name: Modify CIFS share - REST
269 netapp.ontap.na_ontap_cifs:
270 state: present
271 name: cifsShareName
272 path: /
273 vserver: vserverName
274 oplocks: true
275 change_notify: true
276 unix_symlink: local
277 comment: CIFS share description
278 hostname: "{{ netapp_hostname }}"
279 username: "{{ netapp_username }}"
280 password: "{{ netapp_password }}"
281 """
282
283 RETURN = """
284 """
285
286 import traceback
287
288 from ansible.module_utils.basic import AnsibleModule
289 from ansible.module_utils._text import to_native
290 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
291 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
292 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
293
294
295 class NetAppONTAPCifsShare:
296 """
297 Methods to create/delete/modify(path) CIFS share
298 """
299
300 def __init__(self):
301 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
302 self.argument_spec.update(dict(
303 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
304 name=dict(required=True, type='str', aliases=['share_name']),
305 path=dict(required=False, type='str'),
306 comment=dict(required=False, type='str'),
307 vserver=dict(required=True, type='str'),
308 unix_symlink=dict(required=False, type='str', choices=['local', 'widelink', 'disable']),
309 share_properties=dict(required=False, type='list', elements='str'),
310 symlink_properties=dict(required=False, type='list', elements='str'),
311 vscan_fileop_profile=dict(required=False, type='str', choices=['no_scan', 'standard', 'strict', 'writes_only']),
312 access_based_enumeration=dict(required=False, type='bool'),
313 change_notify=dict(required=False, type='bool'),
314 encryption=dict(required=False, type='bool'),
315 home_directory=dict(required=False, type='bool'),
316 oplocks=dict(required=False, type='bool'),
317 show_snapshot=dict(required=False, type='bool'),
318 allow_unencrypted_access=dict(required=False, type='bool'),
319 namespace_caching=dict(required=False, type='bool'),
320 continuously_available=dict(required=False, type='bool'),
321 browsable=dict(required=False, type='bool'),
322 show_previous_versions=dict(required=False, type='bool'),
323 offline_files=dict(required=False, type='str', choices=['none', 'manual', 'documents', 'programs']),
324 ))
325 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
326
327 self.module = AnsibleModule(
328 argument_spec=self.argument_spec,
329 required_if=[
330 ['use_lambda', True, ('lambda_config',)]
331 ],
332 supports_check_mode=True
333 )
334
335 self.na_helper = NetAppModule()
336 self.parameters = self.na_helper.set_parameters(self.module.params)
337
338 # Set up Rest API
339 self.rest_api = netapp_utils.OntapRestAPI(self.module)
340 partially_supported_rest_properties = [['continuously_available', (9, 10, 1)], ['namespace_caching', (9, 10, 1)],
341 ['show_snapshot', (9, 10, 1)], ['offline_files', (9, 10, 1)], ['allow_unencrypted_access', (9, 11)],
342 ['browsable', (9, 13, 1)], ['show_previous_versions', (9, 13, 1)],
343 ['vscan_fileop_profile', (9, 15, 1)]]
344 unsupported_rest_properties = ['share_properties', 'symlink_properties']
345 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, unsupported_rest_properties, partially_supported_rest_properties)
346 self.unsupported_zapi_properties = ['unix_symlink', 'access_based_enumeration', 'change_notify', 'encryption', 'home_directory',
347 'oplocks', 'continuously_available', 'show_snapshot', 'namespace_caching', 'allow_unencrypted_access',
348 'browsable', 'show_previous_versions', 'offline_files']
349 self.svm_uuid = None
350 if not self.use_rest:
351 if self.parameters.get('use_lambda'):
352 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
353 if not netapp_utils.has_netapp_lib():
354 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
355 for unsupported_zapi_property in self.unsupported_zapi_properties:
356 if self.parameters.get(unsupported_zapi_property) is not None:
357 msg = "Error: %s option is not supported with ZAPI. It can only be used with REST." % unsupported_zapi_property
358 self.module.fail_json(msg=msg)
359 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
360
361 def get_cifs_share(self):
362 """
363 Return details about the cifs-share
364 :param:
365 name : Name of the cifs-share
366 :return: Details about the cifs-share. None if not found.
367 :rtype: dict
368 """
369 if self.use_rest:
370 return self.get_cifs_share_rest()
371 cifs_iter = netapp_utils.zapi.NaElement('cifs-share-get-iter')
372 cifs_info = netapp_utils.zapi.NaElement('cifs-share')
373 cifs_info.add_new_child('share-name', self.parameters.get('name'))
374 cifs_info.add_new_child('vserver', self.parameters.get('vserver'))
375
376 query = netapp_utils.zapi.NaElement('query')
377 query.add_child_elem(cifs_info)
378
379 cifs_iter.add_child_elem(query)
380
381 result = self.server.invoke_successfully(cifs_iter, True)
382
383 return_value = None
384 # check if query returns the expected cifs-share
385 if result.get_child_by_name('num-records') and \
386 int(result.get_child_content('num-records')) == 1:
387 properties_list = []
388 symlink_list = []
389 cifs_attrs = result.get_child_by_name('attributes-list').\
390 get_child_by_name('cifs-share')
391 if cifs_attrs.get_child_by_name('share-properties'):
392 properties_attrs = cifs_attrs['share-properties']
393 if properties_attrs is not None:
394 properties_list = [property.get_content() for property in properties_attrs.get_children()]
395 if cifs_attrs.get_child_by_name('symlink-properties'):
396 symlink_attrs = cifs_attrs['symlink-properties']
397 if symlink_attrs is not None:
398 symlink_list = [symlink.get_content() for symlink in symlink_attrs.get_children()]
399 return_value = {
400 'share': cifs_attrs.get_child_content('share-name'),
401 'path': cifs_attrs.get_child_content('path'),
402 'share_properties': properties_list,
403 'symlink_properties': symlink_list
404 }
405 value = cifs_attrs.get_child_content('comment')
406 return_value['comment'] = value if value is not None else ''
407 if cifs_attrs.get_child_by_name('vscan-fileop-profile'):
408 return_value['vscan_fileop_profile'] = cifs_attrs['vscan-fileop-profile']
409
410 return return_value
411
412 def create_cifs_share(self):
413 """
414 Create CIFS share
415 """
416 options = {'share-name': self.parameters.get('name'),
417 'path': self.parameters.get('path')}
418 cifs_create = netapp_utils.zapi.NaElement.create_node_with_children(
419 'cifs-share-create', **options)
420 self.create_modify_cifs_share(cifs_create, 'creating')
421
422 def create_modify_cifs_share(self, zapi_request, action):
423 if self.parameters.get('share_properties'):
424 property_attrs = netapp_utils.zapi.NaElement('share-properties')
425 zapi_request.add_child_elem(property_attrs)
426 for aproperty in self.parameters.get('share_properties'):
427 property_attrs.add_new_child('cifs-share-properties', aproperty)
428 if self.parameters.get('symlink_properties'):
429 symlink_attrs = netapp_utils.zapi.NaElement('symlink-properties')
430 zapi_request.add_child_elem(symlink_attrs)
431 for symlink in self.parameters.get('symlink_properties'):
432 symlink_attrs.add_new_child('cifs-share-symlink-properties', symlink)
433 if self.parameters.get('vscan_fileop_profile'):
434 fileop_attrs = netapp_utils.zapi.NaElement('vscan-fileop-profile')
435 fileop_attrs.set_content(self.parameters['vscan_fileop_profile'])
436 zapi_request.add_child_elem(fileop_attrs)
437 if self.parameters.get('comment'):
438 zapi_request.add_new_child('comment', self.parameters['comment'])
439
440 try:
441 self.server.invoke_successfully(zapi_request,
442 enable_tunneling=True)
443 except netapp_utils.zapi.NaApiError as error:
444
445 self.module.fail_json(msg='Error %s cifs-share %s: %s'
446 % (action, self.parameters.get('name'), to_native(error)),
447 exception=traceback.format_exc())
448
449 def delete_cifs_share(self):
450 """
451 Delete CIFS share
452 """
453 cifs_delete = netapp_utils.zapi.NaElement.create_node_with_children(
454 'cifs-share-delete', **{'share-name': self.parameters.get('name')})
455
456 try:
457 self.server.invoke_successfully(cifs_delete, enable_tunneling=True)
458 except netapp_utils.zapi.NaApiError as error:
459 self.module.fail_json(msg='Error deleting cifs-share %s: %s'
460 % (self.parameters.get('name'), to_native(error)),
461 exception=traceback.format_exc())
462
463 def modify_cifs_share(self):
464 """
465 modilfy path for the given CIFS share
466 """
467 options = {'share-name': self.parameters.get('name')}
468 cifs_modify = netapp_utils.zapi.NaElement.create_node_with_children(
469 'cifs-share-modify', **options)
470 if self.parameters.get('path'):
471 cifs_modify.add_new_child('path', self.parameters.get('path'))
472 self.create_modify_cifs_share(cifs_modify, 'modifying')
473
474 def get_cifs_share_rest(self):
475 """
476 get details of the CIFS share with rest API.
477 """
478 options = {'svm.name': self.parameters.get('vserver'),
479 'name': self.parameters.get('name'),
480 'fields': 'svm.uuid,'
481 'name,'
482 'path,'
483 'comment,'
484 'unix_symlink,'
485 'access_based_enumeration,'
486 'change_notify,'
487 'encryption,'
488 'oplocks,'}
489 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 10, 1):
490 options['fields'] += 'show_snapshot,namespace_caching,continuously_available,offline_files,'
491 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 11, 0):
492 options['fields'] += 'allow_unencrypted_access,'
493 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 13, 1):
494 options['fields'] += 'browsable,show_previous_versions,'
495 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 15, 1):
496 options['fields'] += 'vscan_profile,'
497 api = 'protocols/cifs/shares'
498 record, error = rest_generic.get_one_record(self.rest_api, api, options)
499 if error:
500 self.module.fail_json(msg="Error on fetching cifs shares: %s" % error)
501 if record:
502 self.svm_uuid = record['svm']['uuid']
503 return {
504 'path': record['path'],
505 'comment': record.get('comment', ''),
506 'unix_symlink': record.get('unix_symlink', ''),
507 'access_based_enumeration': record.get('access_based_enumeration'),
508 'change_notify': record.get('change_notify'),
509 'encryption': record.get('encryption'),
510 'oplocks': record.get('oplocks'),
511 'continuously_available': record.get('continuously_available'),
512 'offline_files': record.get('offline_files'),
513 'show_snapshot': record.get('show_snapshot'),
514 'namespace_caching': record.get('namespace_caching'),
515 'allow_unencrypted_access': record.get('allow_unencrypted_access'),
516 'browsable': record.get('browsable'),
517 'show_previous_versions': record.get('show_previous_versions'),
518 'vscan_fileop_profile': record.get('vscan_profile')
519 }
520 return None
521
522 def create_modify_body_rest(self, params=None):
523 body = {}
524 # modify is set in params, if not assign self.parameters for create.
525 if params is None:
526 params = self.parameters
527 options = ['path', 'comment', 'unix_symlink', 'access_based_enumeration', 'change_notify', 'encryption',
528 'home_directory', 'oplocks', 'continuously_available', 'offline_files', 'show_snapshot', 'namespace_caching',
529 'allow_unencrypted_access', 'browsable', 'show_previous_versions', 'vscan_fileop_profile']
530 for key in options:
531 if key in params:
532 if key == 'vscan_fileop_profile':
533 body['vscan_profile'] = params[key]
534 else:
535 body[key] = params[key]
536 return body
537
538 def create_cifs_share_rest(self):
539 """
540 create CIFS share with rest API.
541 """
542 if not self.use_rest:
543 return self.create_cifs_share()
544 body = self.create_modify_body_rest()
545 if 'vserver' in self.parameters:
546 body['svm.name'] = self.parameters['vserver']
547 if 'name' in self.parameters:
548 body['name'] = self.parameters['name']
549 if 'path' in self.parameters:
550 body['path'] = self.parameters['path']
551 api = 'protocols/cifs/shares'
552 dummy, error = rest_generic.post_async(self.rest_api, api, body)
553 if error is not None:
554 self.module.fail_json(msg="Error on creating cifs shares: %s" % error)
555
556 def delete_cifs_share_rest(self):
557 """
558 delete CIFS share with rest API.
559 """
560 if not self.use_rest:
561 return self.delete_cifs_share()
562 body = {'name': self.parameters.get('name')}
563 api = 'protocols/cifs/shares'
564 dummy, error = rest_generic.delete_async(self.rest_api, api, self.svm_uuid, body)
565 if error is not None:
566 self.module.fail_json(msg=" Error on deleting cifs shares: %s" % error)
567
568 def modify_cifs_share_rest(self, modify):
569 """
570 modilfy the given CIFS share with rest API.
571 """
572 if not self.use_rest:
573 return self.modify_cifs_share()
574 api = 'protocols/cifs/shares/%s' % self.svm_uuid
575 body = self.create_modify_body_rest(modify)
576 if body:
577 dummy, error = rest_generic.patch_async(self.rest_api, api, self.parameters['name'], body)
578 if error is not None:
579 self.module.fail_json(msg="Error on modifying cifs shares: %s" % error)
580
581 def apply(self):
582 '''Apply action to cifs share'''
583 current = self.get_cifs_share()
584 cd_action = self.na_helper.get_cd_action(current, self.parameters)
585 # ZAPI accepts both 'show-previous-versions' and 'show_previous_versions', but only returns the latter
586 if not self.use_rest and cd_action is None and 'show-previous-versions' in self.parameters.get('share_properties', [])\
587 and current and 'show_previous_versions' in current.get('share_properties', []):
588 self.parameters['share_properties'].remove('show-previous-versions')
589 self.parameters['share_properties'].append('show_previous_versions')
590 modify = self.na_helper.get_modified_attributes(current, self.parameters) if cd_action is None else None
591
592 if self.na_helper.changed and not self.module.check_mode:
593 if cd_action == 'create':
594 self.create_cifs_share_rest()
595 elif cd_action == 'delete':
596 self.delete_cifs_share_rest()
597 elif modify:
598 self.modify_cifs_share_rest(modify)
599 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
600 self.module.exit_json(**result)
601
602
603 def main():
604 '''Execute action from playbook'''
605 cifs_obj = NetAppONTAPCifsShare()
606 cifs_obj.apply()
607
608
609 if __name__ == '__main__':
610 main()