VhYddlmZmZmZeZdZdZdZddl m Z ddl m Z ddl mZmZmZmZddlmZmZmZdd lZ dd lmZdd lmZmZGd d ZdZedk(rey y #e$rY"wxYw))absolute_importdivisionprint_functiona module: api author: "Nikolay Dachev (@NikolayDachev)" short_description: Ansible module for RouterOS API description: - Ansible module for RouterOS API with the Python C(librouteros) library. - This module can add, remove, update, query, and execute arbitrary command in RouterOS through the API. notes: - O(add), O(remove), O(update), O(cmd), and O(query) are mutually exclusive. - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules for more specific modifications, and the M(community.routeros.api_info) module for a more controlled way of returning all entries for a path. extends_documentation_fragment: - community.routeros.api - community.routeros.attributes - community.routeros.attributes.actiongroup_api attributes: check_mode: support: none diff_mode: support: none platform: support: full platforms: RouterOS action_group: version_added: 2.1.0 idempotent: support: N/A details: - Whether the executed command is idempotent depends on the operation performed. options: path: description: - Main path for all other arguments. - If other arguments are not set, the module will return all items in selected path. - Example V(ip address). Equivalent of RouterOS CLI C(/ip address print). required: true type: str add: description: - Will add selected arguments in selected path to RouterOS config. - Example V(address=1.1.1.1/32 interface=ether1). - Equivalent in RouterOS CLI C(/ip address add address=1.1.1.1/32 interface=ether1). type: str remove: description: - Remove config/value from RouterOS by '.id'. - Example V(*03) will remove config/value with C(id=*03) in selected path. - Equivalent in RouterOS CLI C(/ip address remove numbers=1). - Note C(number) in RouterOS CLI is different from C(.id). type: str update: description: - Update config/value in RouterOS by '.id' in selected path. - Example V(.id=*03 address=1.1.1.3/32) and path V(ip address) will replace the existing IP address with C(.id=*03). - Equivalent in RouterOS CLI C(/ip address set address=1.1.1.3/32 numbers=1). - Note C(number) in RouterOS CLI is different from C(.id). type: str query: description: - Query given path for selected query attributes from RouterOS API. - WHERE is key word which extend query. WHERE format is key operator value - with spaces. - WHERE valid operators are V(==) or V(eq), V(!=) or V(not), V(>) or V(more), V(<) or V(less). - Example path V(ip address) and query V(.id address) will return only C(.id) and C(address) for all items in V(ip address) path. - Example path V(ip address) and query V(.id address WHERE address == 1.1.1.3/32). will return only C(.id) and C(address) for items in V(ip address) path, where address is eq to 1.1.1.3/32. - Example path V(interface) and query V(mtu name WHERE mut > 1400) will return only interfaces C(mtu,name) where mtu is bigger than 1400. - Equivalent in RouterOS CLI C(/interface print where mtu > 1400). type: str extended_query: description: - Extended query given path for selected query attributes from RouterOS API. - Extended query allow conjunctive input. If there is no matching entry, an empty list will be returned. type: dict suboptions: attributes: description: - The list of attributes to return. - Every attribute used in a O(extended_query.where[]) clause need to be listed here. type: list elements: str required: true where: description: - Allows to restrict the objects returned. - The conditions here must all match. An O(extended_query.where[].or) condition needs at least one of its conditions to match. type: list elements: dict suboptions: attribute: description: - The attribute to match. Must be part of O(extended_query.attributes). - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), and O(extended_query.where[].value) have to be specified. type: str is: description: - The operator to use for matching. - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more). - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].value) must be a list. - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), and O(extended_query.where[].value) have to be specified. type: str choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"] value: description: - The value to compare to. Must be a list for O(extended_query.where[].is=in). - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), and O(extended_query.where[].value) have to be specified. type: raw or: description: - A list of conditions so that at least one of them has to match. - Either O(extended_query.where[].or) or all of O(extended_query.where[].attribute), O(extended_query.where[].is), and O(extended_query.where[].value) have to be specified. type: list elements: dict suboptions: attribute: description: - The attribute to match. Must be part of O(extended_query.attributes). type: str required: true is: description: - The operator to use for matching. - For equality use V(==) or V(eq). For less use V(<) or V(less). For more use V(>) or V(more). - Use V(in) to check whether the value is part of a list. In that case, O(extended_query.where[].or[].value) must be a list. type: str choices: ["==", "!=", ">", "<", "in", "eq", "not", "more", "less"] required: true value: description: - The value to compare to. Must be a list for O(extended_query.where[].or[].is=in). type: raw required: true cmd: description: - Execute any/arbitrary command in selected path, after the command we can add C(.id). - Example path V(system script) and cmd V(run .id=*03) is equivalent in RouterOS CLI C(/system script run number=0). - Example path V(ip address) and cmd V(print) is equivalent in RouterOS CLI C(/ip address print). type: str seealso: - ref: ansible_collections.community.routeros.docsite.quoting description: How to quote and unquote commands and arguments. - module: community.routeros.api_facts - module: community.routeros.api_find_and_modify - module: community.routeros.api_info - module: community.routeros.api_modify a --- - name: Get example - ip address print community.routeros.api: hostname: "{{ hostname }}" password: "{{ password }}" username: "{{ username }}" path: "ip address" register: ipaddrd_printout - name: Dump "Get example" output ansible.builtin.debug: msg: '{{ ipaddrd_printout }}' - name: Add example - ip address community.routeros.api: hostname: "{{ hostname }}" password: "{{ password }}" username: "{{ username }}" path: "ip address" add: "address=192.168.255.10/24 interface=ether2" - name: Query example - ".id, address" in "ip address WHERE address == 192.168.255.10/24" community.routeros.api: hostname: "{{ hostname }}" password: "{{ password }}" username: "{{ username }}" path: "ip address" query: ".id address WHERE address == {{ ip2 }}" register: queryout - name: Dump "Query example" output ansible.builtin.debug: msg: '{{ queryout }}' - name: Extended query example - ".id,address,network" where address is not 192.168.255.10/24 or is 10.20.36.20/24 community.routeros.api: hostname: "{{ hostname }}" password: "{{ password }}" username: "{{ username }}" path: "ip address" extended_query: attributes: - network - address - .id where: - attribute: "network" is: "==" value: "192.168.255.0" - or: - attribute: "address" is: "!=" value: "192.168.255.10/24" - attribute: "address" is: "eq" value: "10.20.36.20/24" - attribute: "network" is: "in" value: - "10.20.36.0" - "192.168.255.0" register: extended_queryout - name: Dump "Extended query example" output ansible.builtin.debug: msg: '{{ extended_queryout }}' - name: Update example - ether2 ip address with ".id = *14" community.routeros.api: hostname: "{{ hostname }}" password: "{{ password }}" username: "{{ username }}" path: "ip address" update: >- .id=*14 address=192.168.255.20/24 comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }} - name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14" community.routeros.api: hostname: "{{ hostname }}" password: "{{ password }}" username: "{{ username }}" path: "ip address" remove: "*14" - name: Arbitrary command example "/system identity print" community.routeros.api: hostname: "{{ hostname }}" password: "{{ password }}" username: "{{ username }}" path: "system identity" cmd: "print" register: arbitraryout - name: Dump "Arbitrary command example" output ansible.builtin.debug: msg: '{{ arbitraryout }}' z message: description: All outputs are in list with dictionary elements returned from RouterOS API. sample: - address: 1.2.3.4 - address: 2.3.4.5 type: list returned: always ) AnsibleModule) to_native) ParseErrorconvert_list_to_dictionaryparse_argument_valuesplit_routeros_command)api_argument_speccheck_has_library create_apiN)LibRouterosError)KeyOrcveZdZdZdZddZdZdZdZdZ dZ d Z d Z d Z d Zd ZdZdZddZdZy)ROS_api_modulecttddtdtdtdtdtdtdttdddtddtdtdgd td tddtddtdgdd td dd  dd gdgdg}|jtt|dd|_t |jt |j|_|jjdj|_ |jjd|_ |jjd|_ |jjd|_|jjd|_ d|_|jjd|_|jjd|_tg|_|j%|j|j|_ |jr|j)y|jr|j+y|jr|j-y|jr!|j/|j1y|j r!|j3|j5y|jr|j7y|j9y#t:$r6}|jj=dj?| !Yd}~yd}~wwxYw)"NstrT)typerequired)rdictlist)relementsr) ==!=><ineqnotmoreless)rchoicesraw)rr$r) attributeisvalue)rroptions)r&r'r(or)r&r*)rrr)required_togethermutually_exclusiverequired_one_of) attributeswhere)rr))pathaddremoveupdatecmdqueryextended_queryF))r1r2r3r4r5r6) argument_specsupports_check_moder,r0r1r2r3r4r5r6)messagez"Error while encoding text: {error})errormsg) rr3r rmoduler rapiparamssplitr0r1r2 arbitraryr/r5r6result api_add_pathapi_pathapi_add api_remove api_update check_query api_querycheck_extended_queryapi_extended_query api_arbitrary api_get_allUnicodeEncodeError fail_jsonformat)self module_argsexcs j/home/dcms/DCMS/lib/python3.12/site-packages/ansible_collections/community/routeros/plugins/modules/api.py__init__zROS_api_module.__init__0s540% U#U#% E"VTVedK#%)u%5"7pq!%5!1")-54)H"&E;t@D#E%)ut%DJ (D&D(;'<%8$96 8 ,./#+8=8]_ $++&dkk*KK&&v.446 ;;%%e,kk((2 kk((2 ++E2 [[''0 "kk001AB ))$((DII>  ^xx !!  " $$))+'')""$  "! ^ KK ! !&J&Q&QX[&Q&\ ! ] ] ^s<L<:L<L<4,L<!,L<L<+L<< M;,M66M;c|jjd}|dkr!|j|j|_n|j|tdzd}|j|jd||_t j d|}|s|j d|z |jd|jdt|jdjdg|_ |jjd }|j|dzd|_ |jd||_y#t$r!}|j d|d |Yd}~md}~wwxYw#t$rYywxYw) Nz WHERE rz^\s*([^ ]+)\s+([^ ]+)\s+(.*)$zinvalid syntax for 'WHERE %s'zinvalid syntax for 'WHERE z': WHERE)r5find split_paramslenrematcherrorsgroupr rstripr/rindex ValueError)rQ where_indexr/mrSidxs rTrHzROS_api_module.check_query}sMjjooi0 ?**4::6DJJJ{S^;<=E**4::l{+CDDJ95AA ;eCD PGGAJGGAJ():):)<=a@  **""7+CC!GH-DJDS)DJ  P 5#NOO P    s,-AE?AE3 E0E++E03 E?>E?cl|ddk(r,t|dts|jd||dyyy)Nr'rr(z(invalid syntax 'extended_query':'where':z 'value' must be a type list) isinstancerr`)rQtest_atror_msgs rTcheck_extended_query_syntaxz*ROS_api_module.check_extended_query_syntaxs8 D>T !*Xg5F*M KKflnvw x+N !c|jdrp|jdD]]}|dEt|ddkr|jd|dz|dD]}|j|dM|j|_yy)Nr/r*rXzOinvalid syntax 'extended_query':'where':'or':%s 'or' requires minimum two itemsz:'or':)r6r]r`rl)rQiorvs rTrJz#ROS_api_module.check_extended_querys   w '((1 8T7&1T7|a' $uxyz~x$A wH88hGH44Q7 8 (rmct|ddS)NT)skip_empty_valuesrequire_assignment)r )rQldicts rT list_to_diczROS_api_module.list_to_dics)%4\`aarmct|tstdt|z t |S#t $r/}|j jt|Yd}~yd}~wwxYw)Nz,Parameters can only be a string, received %sr;) rirAssertionErrorrr rr=rOr)rQr?es rTr\zROS_api_module.split_paramss`&#& !ORVW]R^!^_ _ 4)&1 1 4 KK ! !il ! 3 3 4s 4 A,%A''A,cV|j}|D]}|j|}|SN)r0join)rQr>r0rDps rTrCzROS_api_module.api_add_paths/88: (A}}Q'H (rmc |jD] }|jdj|"|jddy#t$r}|j |Yd}~yd}~wwxYw)Nr9FT)rDrBappend return_resultrr`)rQrorxs rTrMzROS_api_module.api_get_alls^ ]] 1 I&--a0 1   ud +  KKNN sAA A( A##A(c@|j|j|j} |jdj d|j jdi|z|j dy#t$r}|j|Yd}~yd}~wwxYw)Nr9zadded: .id= %sT) rur\r1rBr~rDrrr`rQparamrxs rTrEzROS_api_module.api_adds  !2!2488!<=  KK " ) )*:,=DMM,=,=,F,F+G H   t $  KKNN sA A99 BBBc |jj|j|jdjd|jz|j dy#t $r}|j |Yd}~yd}~wwxYw)Nr9zremoved: .id= %sT)rDr2rBr~rrr`rQrxs rTrFzROS_api_module.api_removesi  MM  - KK " ) )*>tDJJqM?RVZV`V`abVc?cdFZZ]m31T]]1148>>tDJJqM?RVZV`V`abVc?cdFZZ]m31T]]1148>>tDJJqM?RUYU_U_`aUb?bcFZZ]m31T]]1148>>tDJJqM?RUYU_U_`aUb?bcFKK B"&**Q-!01.--t4 3 I&--c2 34;;y)*Q.9<$))9L9<$**9MO:: chhtzz.B BBC I&--c2   u %  KKNN sJK K,K''K,c|d|jdvr$|jd|d|jd|ddvr|j|d|dk(S|ddvr|j|d|dk7S|dd vr|j|d|dkS|dd vr|j|d|dkDS|dd k(r"|j|dj|dS|jd |dzy) Nr&r.'z"' attribute is not in attributes: r')r rr()r!r)r#r)r"rrz'%s' is not operator for 'is')r6r` query_keysIn)rQitems rTbuild_api_extended_queryz'ROS_api_module.build_api_extended_querys(  D$7$7 $E E KK!4!4\!BD E : %??4 #45gF F $Z= (??4 #45gF F $Z= (??4 #45W E E $Z= (??4 #45W E E $Z4 84??4 #4588$w-H H KK7$t*D Ermc"i|_|jdD]3}|dk(r|jd|zt||j|<5 |jdrg}|jdD]k}|drDg}|dD]"}|j |j |$|j t |L|j |j |m|jj|jj|}n&|jj|jd}|D] }|jdj |"|jdy#t$r}|j|Yd}~yd}~wwxYw)Nr.rz0'extended_query':'attributes':'%s' must be '.id'r/r*r9F) rr6r`rr~rrrDrr/rBrr) rQr where_argsro where_or_argsiorrrrxs rTrKz!ROS_api_module.api_extended_querys$$\2 (ADy NQRRS!$QDOOA  ( ""7+ ,,W5LAw(* #$T7UC)001N1Ns1STU"))"m*<="))$*G*G*JKLF---t?EEzR---t/B/B>:..# t~~  "$$T^^AB%78E ,t}}W>> % 1 I&--a0 1   u %  KKNN s)A B33 C<CCc|s*|jj|jdy|jj||jdy)Nr9r;)changedr<)r=rOrB exit_json)rQ ch_statusstatuss rTrzROS_api_module.return_result6sH KK ! !dkk)&< ! = KK ! !)&*kk)&< " >rmc|jjdk(r3|jdjd|z|j dd|jdjd|z|j ddy)N TrapErrorr9z%sF) __class____name__rBr~rrs rTr`zROS_api_module.errors=sj ;;  ; . KK " ) )$( 3   ue , I%%dQh/ 5%(rmN))FT)r __module__ __qualname__rUrHrlrJrur\rCrMrErFrGrIrrKrLrr`rrmrTrr/s^K^Z6y 8b4  BF"4 >)rmrctyrz)rrrmrTmainrEsrm__main__) __future__rrrr __metaclass__ DOCUMENTATIONEXAMPLESRETURNansible.module_utils.basicr+ansible.module_utils.common.text.convertersrCansible_collections.community.routeros.plugins.module_utils.quotingrr r r ?ansible_collections.community.routeros.plugins.module_utils.apir r rr^librouteros.exceptionsrlibrouteros.queryrr ExceptionrrrrrmrTrsCB Y vc J 5A   7) S)S)l  zFA   sA##A+*A+