a )g@sbddlmZmZmZeZdZdZdZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZmZddlmZmZddlmZdd lmZmZdaGd d d eZGd d d eZGdddeZddZddZ ddZ!ddZ"ddZ#ddZ$d5ddZ%ddZ&d d!Z'd"d#Z(d$d%Z)d&d'Z*d(d)Z+d*d+Z,d,d-Z-d.d/Z.d0d1Z/d2d3Z0e1d4kr^e0dS)6)absolute_importdivisionprint_functionaZ --- module: file version_added: historical short_description: Manage files and file properties extends_documentation_fragment: [files, action_common_attributes] description: - Set attributes of files, directories, or symlinks and their targets. - Alternatively, remove files, symlinks or directories. - Many other modules support the same options as the C(file) module - including M(ansible.builtin.copy), M(ansible.builtin.template), and M(ansible.builtin.assemble). - For Windows targets, use the M(ansible.windows.win_file) module instead. options: path: description: - Path to the file being managed. type: path required: yes aliases: [ dest, name ] state: description: - If C(absent), directories will be recursively deleted, and files or symlinks will be unlinked. In the case of a directory, if C(diff) is declared, you will see the files and folders deleted listed under C(path_contents). Note that C(absent) will not cause C(file) to fail if the C(path) does not exist as the state did not change. - If C(directory), all intermediate subdirectories will be created if they do not exist. Since Ansible 1.7 they will be created with the supplied permissions. - If C(file), with no other options, returns the current state of C(path). - If C(file), even with other options (such as C(mode)), the file will be modified if it exists but will NOT be created if it does not exist. Set to C(touch) or use the M(ansible.builtin.copy) or M(ansible.builtin.template) module if you want to create the file if it does not exist. - If C(hard), the hard link will be created or changed. - If C(link), the symbolic link will be created or changed. - If C(touch) (new in 1.4), an empty file will be created if the file does not exist, while an existing file or directory will receive updated file access and modification times (similar to the way C(touch) works from the command line). - Default is the current state of the file if it exists, C(directory) if C(recurse=yes), or C(file) otherwise. type: str choices: [ absent, directory, file, hard, link, touch ] src: description: - Path of the file to link to. - This applies only to C(state=link) and C(state=hard). - For C(state=link), this will also accept a non-existing path. - Relative paths are relative to the file being created (C(path)) which is how the Unix command C(ln -s SRC DEST) treats relative paths. type: path recurse: description: - Recursively set the specified file attributes on directory contents. - This applies only when C(state) is set to C(directory). type: bool default: no version_added: '1.1' force: description: - > Force the creation of the symlinks in two cases: the source file does not exist (but will appear later); the destination exists and is a file (so, we need to unlink the C(path) file and create symlink to the C(src) file in place of it). type: bool default: no follow: description: - This flag indicates that filesystem links, if they exist, should be followed. - I(follow=yes) and I(state=link) can modify I(src) when combined with parameters such as I(mode). - Previous to Ansible 2.5, this was C(false) by default. type: bool default: yes version_added: '1.8' modification_time: description: - This parameter indicates the time the file's modification time should be set to. - Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now). - Default is None meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch). type: str version_added: "2.7" modification_time_format: description: - When used with C(modification_time), indicates the time format that must be used. - Based on default Python format (see time.strftime doc). type: str default: "%Y%m%d%H%M.%S" version_added: '2.7' access_time: description: - This parameter indicates the time the file's access time should be set to. - Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now). - Default is C(None) meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch). type: str version_added: '2.7' access_time_format: description: - When used with C(access_time), indicates the time format that must be used. - Based on default Python format (see time.strftime doc). type: str default: "%Y%m%d%H%M.%S" version_added: '2.7' seealso: - module: ansible.builtin.assemble - module: ansible.builtin.copy - module: ansible.builtin.stat - module: ansible.builtin.template - module: ansible.windows.win_file attributes: check_mode: support: full diff_mode: details: permissions and ownership will be shown but file contents on absent/touch will not. support: partial platform: platforms: posix author: - Ansible Core Team - Michael DeHaan a$ - name: Change file ownership, group and permissions ansible.builtin.file: path: /etc/foo.conf owner: foo group: foo mode: '0644' - name: Give insecure permissions to an existing file ansible.builtin.file: path: /work owner: root group: root mode: '1777' - name: Create a symbolic link ansible.builtin.file: src: /file/to/link/to dest: /path/to/symlink owner: foo group: foo state: link - name: Create two hard links ansible.builtin.file: src: '/tmp/{{ item.src }}' dest: '{{ item.dest }}' state: hard loop: - { src: x, dest: y } - { src: z, dest: k } - name: Touch a file, using symbolic modes to set the permissions (equivalent to 0644) ansible.builtin.file: path: /etc/foo.conf state: touch mode: u=rw,g=r,o=r - name: Touch the same file, but add/remove some permissions ansible.builtin.file: path: /etc/foo.conf state: touch mode: u+rw,g-wx,o-rwx - name: Touch again the same file, but do not change times this makes the task idempotent ansible.builtin.file: path: /etc/foo.conf state: touch mode: u+rw,g-wx,o-rwx modification_time: preserve access_time: preserve - name: Create a directory if it does not exist ansible.builtin.file: path: /etc/some_directory state: directory mode: '0755' - name: Update modification and access time of given file ansible.builtin.file: path: /etc/some_file state: file modification_time: now access_time: now - name: Set access time based on seconds from epoch value ansible.builtin.file: path: /etc/another_file state: file access_time: '{{ "%Y%m%d%H%M.%S" | strftime(stat_var.stat.atime) }}' - name: Recursively change ownership of a directory ansible.builtin.file: path: /etc/foo state: directory recurse: yes owner: foo group: foo - name: Remove file (delete file) ansible.builtin.file: path: /etc/foo.txt state: absent - name: Recursively remove directory ansible.builtin.file: path: /etc/foo state: absent ak dest: description: Destination file/path, equal to the value passed to I(path). returned: state=touch, state=hard, state=link type: str sample: /path/to/file.txt path: description: Destination file/path, equal to the value passed to I(path). returned: state=absent, state=directory, state=file type: str sample: /path/to/file.txt N)getpwnamgetpwuid)getgrnamgetgrgid) AnsibleModule)to_bytes to_nativec@seZdZddZddZdS)AnsibleModuleErrorcCs ||_dSNresults)selfrr8/usr/lib/python3.9/site-packages/ansible/modules/file.py__init__szAnsibleModuleError.__init__cCs d|jS)NzAnsibleModuleError(results={0}))formatr)rrrr__repr__szAnsibleModuleError.__repr__N)__name__ __module__ __qualname__rrrrrrr sr c@s eZdZdS)ParameterErrorN)rrrrrrrrsrc@seZdZddZdS)SentinelcOs|Sr r)clsargskwargsrrr__new__szSentinel.__new__N)rrrrrrrrrsrcCs0t|trtjfi|jnt|||dSr ) issubclassr moduleZ fail_jsonrsys__excepthook__)exc_type exc_valuetbrrr_ansible_excepthooks r&cCs|ddvrltjt|dddrld}|dr:|d}n|drRtj|d}|rltj|d||d<tt|ddd}|ddur|d kr||d<n|d rd |d<nd |d<|d r|dd krtd |ddd|dr |ddvr td|ddddS)z0Additional parameter validation and reformattingstate)linkabsentpathsurrogate_or_stricterrorsN_original_basenamesrcr)recurse directoryfilez/recurse option requires state to be 'directory'msgr*r)r(hardz0src option requires state to be 'link' or 'hard')osr*isdirr basenamejoin get_stater)paramsr8 prev_staterrradditional_parameter_handlings. $     r=c Cst|dd}zRtj|rZtj|r,WdStj|r>WdSt|jdkrTWdSWdSWdSty}z(|j t j krWYd }~dSWYd }~n d }~00d S) z Find out current state r+r,r(r1r5r2r)N) r r6r*lexistsislinkr7statst_nlinkOSErrorerrnoENOENT)r*b_patherrrr:>s     r:c Csd}zNt|D]<\}}}||D]&} tj|| } tj| s|} t| dd| d<|tj| |ddO}|t | d||O}q&|} t| dd| d<|tj| |ddO}|t | d||O}|r&tj|t | } tj | r&tj | r|t | ||||O}|} t| dd| d<|tj| |ddO}|t | d||O}q&qWnDty} z*tddt|t| fidWYd} ~ n d} ~ 00|S) NFr+r,r*expandr4zDCould not recursively set attributes on %s. Original error was: '%s'r)r6walkr*r9r@copyr r set_fs_attributes_if_differentupdate_timestamp_for_filereadlinkexistsr7recursive_set_attributes RuntimeErrorr ) rFfollow file_argsmtimeatimechangedZb_rootZb_dirsZb_filesZb_fsobjZb_fsname tmp_file_argsrGrrrrPWs8  rPc Csd|id|id}||kr||dd<||dd<|dkr|dkrggd}t|d d }t|D]V\}}}|D] } tj|| } |d | qp|D] } tj|| } |d | qqb||dd <|S)Nr*)beforeafterrXr'rYr)r1) directoriesfilesr+r,rZr[Z path_content)r r6rJr*r9append) r*r'r<diffZwalklistrF base_pathZ sub_foldersr[ZfolderZ folderpathfilenamefilepathrrr initial_diffs(    rac Cs|dkr dS|dkrtSzt||}t|}WnHttfyz}z,tdd||t|ddfidWYd}~n d}~00|SdS)Npreservenowr4z?Error while obtaining timestamp for time %s using format %s: %s simplereprZ nonstringr)rtimestrptimemktime ValueError OverflowErrorr r )Zformatted_timeZ time_formatstruct struct_timerGrrrget_timestamp_for_times  rmc Cst|dd}zH|turJ|turJt}}t|j}t|j}d}n|dur`|dur`WdSt|j}t|j}|dur|}n|turt}|dur|}n|turt}||kr||krWdS||f}tjst |||durTd|vri|d<d|vri|d<||kr2||dd<||dd<||krT||dd<||dd<WnBt y}z(t dt |d d |d d WYd}~n d}~00d S)Nr+r,FrXrYrTrUz4Error while updating modification or access time: %srdrer3rT) r rrfr6rAst_mtimest_atimer check_modeutimerCr r ) r*rTrUr]rFZprevious_mtimeZprevious_atimeZset_timerGrrrrMsT                rMcCs0|dvr|durdS|dkr(|dur(dS|SdS)N)r2r5r1r(rbtouchrcr)Z parameterr'rrr)keep_backward_compatibility_on_timestampss rscCslt|dd}d}z8t|d}|d}Wdn1s<0YWntyZYn0d|vrhd}|S) z2Take a guess as to whether a file is a binary filer+r,Frbi NT)r openread Exception)r*rFappears_binaryfheadrrrexecute_diff_peeks  , r|c Cst|dd}t|}i}|dkrt|d|}tjs|dkrztj|ddWqty}z"tddt |id WYd}~qd}~00nXzt |WnHt y}z0|j t jkrtd t ||d d WYd}~n d}~00||d |dd n||ddd|S)Nr+r,r)r1F) ignore_errorsr4zrmtree failed: %srzunlinking failed: %s r3T)r*rVr]r')r*rVr')r r:rar rpshutilrmtreerxr r r6unlinkrCrDrEupdate)r*rFr<resultr]rGrrr ensure_absents*  .   rc CsXt|dd}t|}d}d|i}t|d|d}t|d|d}|d krtjr^d |d <|Szt|d d }WnDttfy} z(t d t | dd|ddWYd} ~ n d} ~ 00t |d|} t tj } z,tj| || dd}|t| d||| O}WnDtyB} z*| jr,|d kr,t|WYd} ~ n d} ~ 00||d <| |d<|S)Nr+r,Fdestmodification_timemodification_time_format access_timeaccess_time_formatr)TrVwbz!Error, could not touch target: %srdrer3rrrrHr*r])r r:rmr rprvcloserCIOErrorr r raload_file_common_argumentsr;rLrM SystemExitcoder6remove) r*rR timestampsrFr<rVrrTrUrGr]rSrrr execute_touch$s@       rc Cst|dd}t|}ttj}t|d|d}t|d|d}|dkr|r|dkrtj|}t |d d}t|}||d <|d vrt d ||f||d dt |d|}tj |d|dd} | t |d |||O} || |dS)Nr+r,rrrrr2r(strictr*r2r5z file (%s) is %s, cannot continue)r4r*r'rFrHr*rVr])r r:r rr;rmr6r*realpathr r rarLrM) r*rRrrFr<rSrTrUr]rVrrrensure_file_attributesOs&        rc CsNt|dd}t|}ttj}t|d|d}t|d|d}|rx|dkrxtj|}t |dd}||d <t|}d } t |d |} |d krtj r|d | dSd} z| d dD]} d| | g} tj|s| d} t| dd} tj| szt| d } WnDtyP}z*|jtjkr:tj| s<WYd}~n d}~00|}| |d <tj|| | d d} | t|d ||| O} qWnBty}z(td| t |f|ddWYd}~n d}~00|| | dS|d krtd||f|ddtj|| | d d} | t|d ||| O} |rB| t|||||O} || | dS)Nr+r,rrrrr(rr*Fr1r)Tr/rHz/There was an issue creating %s as requested: %sr3rz%s already exists as a %s)r r:r rr;rmr6r*rr rarpstripsplitr9isabslstriprOmkdirrCrDZEEXISTr7rKrLrMrxr rP)r*rRr0rrFr<rSrTrUrVr]ZcurpathdirnameZ b_curpathexrWrGrrrensure_directoryisb                   rc Cst|dd}t|dd}t|}t|d|d}t|d|d} |durz|rztj|rztt|dd}t|dd}tj|stj |r|} ntj |} t| dd} |durd} ntj | |} t| dd} |s |dur tj| s t d| ||d d |d krX|s6t d ||f|d d n t |rt d||d d n(|dvr|st d ||f|d d t|d|}d}|dvr|durt ddid d}n`|dkr|durt|}||krt|dd|dd<||dd<d}nt d||dd |rDtjsD|dkrttjj tj |tdttfg}z0|d krxt|t||t||WnZty}z@tj|rt|t dt|dd|d d WYd}~n d}~00nTzt||WnBtyB}z(t d t|dd|d d WYd}~n d}~00tjrhtj|sh||||d!Sttj}|rtj|rtj|d"std#n(tj|||dd$}|t|d"|| |O}||||d!S)%Nr+r,rrrrrzRsrc file does not exist, use "force=yes" if you really want to create the link: %s)r4r*r/rr1z-refusing to convert from %s to symlink for %sr3z5the directory %s is not empty, refusing to convert itrr(F)r5r2r1r)r4z)src is required for creating new symlinksTrXr/rYunexpected position reachedr4rr/r) .%s.%s.tmpError while replacing: %srdreError while linking: %srr/rVr]r*zgCannot set fs attributes on a non-existent symlink target. follow should be set to False to avoid this.rH)r r:rmr6r*rOr rNr@r7rr9r listdirrar rpsepgetpidrfrmdirsymlinkrenamerCrrr;warnrLrM)r*r/rRforcerrFb_srcr<rTrUrelpathZ b_relpathZabsrcZb_absrcr]rV b_old_src b_tmppathrGrSrrrensure_symlinks                      "     "   & rc Cst|dd}t|dd}t|}ttj}t|d|d} t|d|d} |dkrn|durntdd id |durtj |std ||d d t |d|} d } |dkrd} n$|dkrt |} | |krt | dd| dd<|| dd<d} n|dkr@|durt |jt |jksd} |std||d d n|dkrld} |std|||d d nl|dkrd} tj |rt |jt |jkr|d dS|std||d d ntd||d d | rNtjsN|dkrttjjtj|tdttfg}zz|dkrtj |rzt|Wn6ty}z|jtjkrlWYd}~n d}~00t||t||WnZty}z@tj |rt|tdt |dd|d d WYd}~n d}~00nTzt||WnBtyL}z(td!t |dd|d d WYd}~n d}~00tjrrtj |sr||| | d"Stj|| | d d#} | t|d$| | | O} ||| | d"S)%Nr+r,rrrrr5r4z*src is required for creating new hardlinksrzsrc does not existrFr)Tr(rrXr/rYz6Cannot link, different hard link exists at destinationr2z%Cannot link, %s exists at destinationr1)r*rVz6Cannot link: different hard link exists at destinationrrrrdrer3rrrHr*)r r:r rr;rmr r6r*rOrarNr rAst_inorprr9rrrfrrCrDrEr(rrLrM)r*r/rRrrrFrr<rSrTrUr]rVrrrGrrrensure_hardlinks       $        "    "  rc CszsJtZ  .+  ; +GoZE