Current File : //lib/python2.7/site-packages/salt/states/file.pyo
�
���^c $ @@ s� d Z d d l m Z m Z m Z d d l Z d d l Z d d l Z d d l Z d d l Z d d l
Z
d d l Z d d l Z d d l
Z
d d l Z d d l Z d d l m Z m Z m Z d d l m Z m Z d d l Z d d l Z d d l Z d d l Z d d l Z d d l Z d d l Z d d l Z d d l Z d d l Z d d l! Z d d l" Z d d l# Z d d l$ m% Z% d d l& m' Z' d d l( m) Z* e j+ j, j- � r�d d l. Z d d l/ Z d d l0 Z n d d l1 m2 Z2 d d
l3 m4 Z4 d d l5 m6 Z7 e j+ j, j- � r:d d l8 Z8 d d l9 Z: n e j; e< � Z= d Z> e? � Z@ i d
d 6ZA d � ZB d � ZC d � ZD d � ZE eF d � ZG d � ZH eI eF eF eF eI d � ZJ eF d � ZK d � ZL d � ZM d � ZN d � ZO eF eF eI eF eF eI eI eF eF eI d �
ZP eF eF eF eF eF d � ZQ eI d � ZR d � ZS d � ZT d � ZU d! � ZV d" � ZW eF d# � ZX eF eF eF eF d$ � ZY eF d% eF eF d& � ZZ eF d' � Z[ d( � Z\ d) � Z] d* � Z^ d+ � Z_ eF eF eF eF eF eF eF d, � Z` eI eF eI eF eF eF eF eF eF eF d- �
Za d. � Zb d eF eI d d/ � Zc d0 � Zd d1 � Ze eF d2 eF ef eF eF eF eF eF eI eF eF ef eF d2 ef ef eF d2 d2 eF eF ef d3 eF d4 ef ef eF eI eF eF eF ef eI d5 �# Zg d6 d7 d8 d9 d: g Zh d; � Zi eF d< � Zj eF eF eF eF eF eF eI eI eF eF eI eI eF ef eI eF eF eF ef eI d= � Zk ef eI eF eF eF eF eF eF eF eF ef eF eI d2 eF eF eF eI eI eF eF eF ef d> � Zl eF eF d? � Zm eF eF eF eF eF eF ef eI eI ef eI eF eF eF d@ � Zn d dA dB eI eI eF dC ef eI eI dD �
Zo dE dF eF eF d% eF eF eF eF d2 eI eI dC ef eF dG � Zp dH dC dI � Zq dH dC dJ � Zr eF eI eF eF d% eF eF eF eF ef dK �
Zs eF eI eF eF d% eF eF eF eF eF dL �
Zt eF eF eF eI eF eF eF d2 eF eF eF dM � Zu eF eF eI dN � Zv eI eI eI eF eF eF eI dO � Zw eI eI dP � Zx dQ � Zy eF eF eF eF eF d2 eI ef ef eI eF d4 eF eF dR � Zz d d eF eF dS dT � Z{ dU � Z| eF eF dV dW dX � Z} eF eF eF eF eI eF eI eF dY � Z~ d2 eF eI dZ d[ � Z dZ d\ � Z� d S(] u�!
Operations on regular files, special files, directories, and symlinks
=====================================================================
Salt States can aggressively manipulate files on a system. There are a number
of ways in which files can be managed.
Regular files can be enforced with the :mod:`file.managed
<salt.states.file.managed>` state. This state downloads files from the salt
master and places them on the target system. Managed files can be rendered as a
jinja, mako, or wempy template, adding a dynamic component to file management.
An example of :mod:`file.managed <salt.states.file.managed>` which makes use of
the jinja templating system would look like this:
.. code-block:: jinja
/etc/http/conf/http.conf:
file.managed:
- source: salt://apache/http.conf
- user: root
- group: root
- mode: 644
- attrs: ai
- template: jinja
- defaults:
custom_var: "default value"
other_var: 123
{% if grains['os'] == 'Ubuntu' %}
- context:
custom_var: "override"
{% endif %}
It is also possible to use the :mod:`py renderer <salt.renderers.py>` as a
templating option. The template would be a Python script which would need to
contain a function called ``run()``, which returns a string. All arguments
to the state will be made available to the Python script as globals. The
returned string will be the contents of the managed file. For example:
.. code-block:: python
def run():
lines = ['foo', 'bar', 'baz']
lines.extend([source, name, user, context]) # Arguments as globals
return '\n\n'.join(lines)
.. note::
The ``defaults`` and ``context`` arguments require extra indentation (four
spaces instead of the normal two) in order to create a nested dictionary.
:ref:`More information <nested-dict-indentation>`.
If using a template, any user-defined template variables in the file defined in
``source`` must be passed in using the ``defaults`` and/or ``context``
arguments. The general best practice is to place default values in
``defaults``, with conditional overrides going into ``context``, as seen above.
The template will receive a variable ``custom_var``, which would be accessed in
the template using ``{{ custom_var }}``. If the operating system is Ubuntu, the
value of the variable ``custom_var`` would be *override*, otherwise it is the
default *default value*
The ``source`` parameter can be specified as a list. If this is done, then the
first file to be matched will be the one that is used. This allows you to have
a default file on which to fall back if the desired file does not exist on the
salt fileserver. Here's an example:
.. code-block:: jinja
/etc/foo.conf:
file.managed:
- source:
- salt://foo.conf.{{ grains['fqdn'] }}
- salt://foo.conf.fallback
- user: foo
- group: users
- mode: 644
- attrs: i
- backup: minion
.. note::
Salt supports backing up managed files via the backup option. For more
details on this functionality please review the
:ref:`backup_mode documentation <file-state-backups>`.
The ``source`` parameter can also specify a file in another Salt environment.
In this example ``foo.conf`` in the ``dev`` environment will be used instead.
.. code-block:: yaml
/etc/foo.conf:
file.managed:
- source:
- 'salt://foo.conf?saltenv=dev'
- user: foo
- group: users
- mode: '0644'
- attrs: i
.. warning::
When using a mode that includes a leading zero you must wrap the
value in single quotes. If the value is not wrapped in quotes it
will be read by YAML as an integer and evaluated as an octal.
The ``names`` parameter, which is part of the state compiler, can be used to
expand the contents of a single state declaration into multiple, single state
declarations. Each item in the ``names`` list receives its own individual state
``name`` and is converted into its own low-data structure. This is a convenient
way to manage several files with similar attributes.
.. code-block:: yaml
salt_master_conf:
file.managed:
- user: root
- group: root
- mode: '0644'
- names:
- /etc/salt/master.d/master.conf:
- source: salt://saltmaster/master.conf
- /etc/salt/minion.d/minion-99.conf:
- source: salt://saltmaster/minion.conf
.. note::
There is more documentation about this feature in the :ref:`Names declaration
<names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.
Special files can be managed via the ``mknod`` function. This function will
create and enforce the permissions on a special file. The function supports the
creation of character devices, block devices, and FIFO pipes. The function will
create the directory structure up to the special file if it is needed on the
minion. The function will not overwrite or operate on (change major/minor
numbers) existing special files with the exception of user, group, and
permissions. In most cases the creation of some special files require root
permissions on the minion. This would require that the minion to be run as the
root user. Here is an example of a character device:
.. code-block:: yaml
/var/named/chroot/dev/random:
file.mknod:
- ntype: c
- major: 1
- minor: 8
- user: named
- group: named
- mode: 660
Here is an example of a block device:
.. code-block:: yaml
/var/named/chroot/dev/loop0:
file.mknod:
- ntype: b
- major: 7
- minor: 0
- user: named
- group: named
- mode: 660
Here is an example of a fifo pipe:
.. code-block:: yaml
/var/named/chroot/var/log/logfifo:
file.mknod:
- ntype: p
- user: named
- group: named
- mode: 660
Directories can be managed via the ``directory`` function. This function can
create and enforce the permissions on a directory. A directory statement will
look like this:
.. code-block:: yaml
/srv/stuff/substuf:
file.directory:
- user: fred
- group: users
- mode: 755
- makedirs: True
If you need to enforce user and/or group ownership or permissions recursively
on the directory's contents, you can do so by adding a ``recurse`` directive:
.. code-block:: yaml
/srv/stuff/substuf:
file.directory:
- user: fred
- group: users
- mode: 755
- makedirs: True
- recurse:
- user
- group
- mode
As a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to
specify both directory and file permissions, use this form:
.. code-block:: yaml
/srv/stuff/substuf:
file.directory:
- user: fred
- group: users
- file_mode: 744
- dir_mode: 755
- makedirs: True
- recurse:
- user
- group
- mode
Symlinks can be easily created; the symlink function is very simple and only
takes a few arguments:
.. code-block:: yaml
/etc/grub.conf:
file.symlink:
- target: /boot/grub/grub.conf
Recursive directory management can also be set via the ``recurse``
function. Recursive directory management allows for a directory on the salt
master to be recursively copied down to the minion. This is a great tool for
deploying large code and configuration systems. A state using ``recurse``
would look something like this:
.. code-block:: yaml
/opt/code/flask:
file.recurse:
- source: salt://code/flask
- include_empty: True
A more complex ``recurse`` example:
.. code-block:: jinja
{% set site_user = 'testuser' %}
{% set site_name = 'test_site' %}
{% set project_name = 'test_proj' %}
{% set sites_dir = 'test_dir' %}
django-project:
file.recurse:
- name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}
- user: {{ site_user }}
- dir_mode: 2775
- file_mode: '0644'
- template: jinja
- source: salt://project/templates_dir
- include_empty: True
Retention scheduling can be applied to manage contents of backup directories.
For example:
.. code-block:: yaml
/var/backups/example_directory:
file.retention_schedule:
- strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2
- retain:
most_recent: 5
first_of_hour: 4
first_of_day: 14
first_of_week: 6
first_of_month: 6
first_of_year: all
i ( t absolute_importt print_functiont unicode_literalsN( t Iterablet Mappingt defaultdict( t datetimet date( t CommandExecutionError( t DeserializationError( t get_accumulator_dir( t six( t zip_longest( t urlparseu ^([[:space:]]*){0}[[:space:]]?u copyu copy_c C@ s t j j t t d � t � S( u'
Return accumulator data path.
u cachedir( t ost patht joint _get_accumulator_dirt __opts__t __instance_id__( ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _get_accumulator_filepathR s
c C@ s* d � } | t � � } | d | d f S( Nc S@ s� t j j t � } i i d 6i d 6} yB t j j j | d � �$ } | j | � } | r] | S| SWd QXWn t t f k
r� | SXd S( Nu accumulatorsu accumulators_depsu rb(
t saltt payloadt SerialR t utilst filest fopent loadt IOErrort NameError( R t serialt rett ft loaded( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _deserialize] s u accumulatorsu accumulators_deps( R ( R" R! ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _load_accumulators\ s c C@ sv i | d 6| d 6} t j j t � } y8 t j j j t � d � � } | j | | � Wd QXWn t k
rq n Xd S( Nu accumulatorsu accumulators_depsu w+b(
R R R R R R R R t dumpR ( t accumulatorst accumulators_depst accumm_dataR R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _persist_accummulatorsm s
c C@ s� d } | rA t d | � } | d k rA | d j | � 7} qA n | r| t d | � } | d k r| | d j | � 7} q| n | S( uF
Checks if the named user and group are present on the minion
u u file.user_to_uidu User {0} is not available u file.group_to_gidu Group {0} is not available( t __salt__t format( t usert groupt errt uidt gid( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_userz s c C@ sn t j t j } } | | | | | | k r3 t S| d k rj | j | � j | � } | | k rj t Sn t S( u2
Performs basic sanity checks on a relative path.
Requires POSIX-compatible paths (i.e. the kind obtained through
cp.list_master or other such calls).
Ensures that the path does not contain directory transversal, and
that it does not exceed a stated maximum depth (if specified).
N( t posixpatht sept pardirt Falset Nonet stript countt True( t relpatht maxdepthR2 R3 t
path_depth( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _is_valid_relpath� s c C@ s% t j j | j t j t j j � � S( ud
Converts a path from the form received via salt master to the OS's native
path format.
( R R t normpatht replaceR1 R2 ( R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _salt_to_os_path� s c @ s� � f d � � � � � � � � � � f d � } t � } t � }
t � � t � � t � � t j j j | � \ � } | d
k r� t } n � j t j � s� � t j � n t
d | � � } | r� t
d | � � }
| | |
� } n x� | D]� } | j � sq� n t j j j
t j | � � � } t | d � �sHq� n t j j j | � � � siq� n � | � } t j j | � } � j | � | � k r�|
j | � � j | � n t j j j | d | �} | j | | f � q� W| r�t
d | � � } x� | D]� } t j | � � } t | d � �s?qn t j j j | � � � s`qn � | � } | r�t } x@ |
D]8 } | j | d � rt j d j | � � t } PqqW| r�qq�n |
j | � � j | � qWn | |
� � f S( u?
Generate the list of files managed by a recurse state
c @ s t j j � t | � � S( N( R R R R? ( t master_relpath( t name( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt full_path� s c @ s� x� t j | � D]� \ } } t j | � � } t | d � �sF q n t j j j | � � � sg q n t | � } xC | D]; } | j
| � rz t j d j
| � � | j | � qz qz W� j | | f � � j � | � � q W� j � � | S( NR: u0 ** skipping file ** {0}, it intersects a symlink( R t iteritemsR1 R9 R< R R t stringutilst check_include_excludet listt
startswitht logt debugR* t removet addt update( t filenamest symlinkst lnamet ltargett srelpatht
_filenamest filename( t exclude_patRB t include_patt keept managed_symlinksR: t srcpatht vdir( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt process_symlinks� s"
u cp.list_masteru cp.list_master_symlinksR: t saltenvu cp.list_master_dirsi u5 ** skipping empty dir ** {0}, it intersects a symlinkN( t setR R t urlt parseR5 t __env__t endswithR1 R2 R) R6 t datat decodeR9 R< RD RE R R t dirnameRK t createR4 RG RH RI R* R8 ( RA t sourcet
keep_symlinksRU RT R: t
include_emptyt kwargsRZ t
managed_filest managed_directoriest senvt fns_RN t fn_t relnamet destRc t srct mdirst mdirt mdestt islinkt link( ( RT RB RU RV RW R: RA RX RY s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _gen_recurse_managed_files� sp $
!
c @ s� d � } � f d � � � � � � f d � � d � } t � } t | t � r�g | D] } d | k rX | ^ qX } x| D]} xt D]� } | d | d k s� | d | d k r� | d } | d }
t j j | � rw| | | � r�|
d k r2t | � d
} t j d j
| | � � | j | � qt� r^t � � � | � � | j � � qt| j | | � � q�q�| j | � q� q� Wq} Wn t j d j
t | � � � t | � S(
u~
Generate the list of files that need to be kept when a dir based function
like directory or recurse has a clean.
c S@ sJ t j j | � } t j j | � } t j j | | � } | j t j � S( uB
Check whether ``path`` is child of ``directory``
( R R t abspathR9 RG R3 ( R t directoryt relative( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _is_child. s c @ s� t � } t j j | � r� � j | d d f � \ } } | j | � x* | D]" } | j t j j | | � � qM Wx- | D]" } | j t j j | | � � qz Wn | S( N( ( ( R\ R R t isdirt getRK R ( R t _rett dirsR t _name( t walk_d( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _add_current_path9 s
#c @ s� t j j | � r� � j � | � � � j | d d f � \ } } xF | D]; } t j j | | � } � j � | � � � | | � qJ Wn d S( N( ( ( R R R{ RL R| R ( RA R R~ t _t _dt p( R� t _process_by_walk_dR� t walk_ret( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� D s
c S@ s� t � } t j j | � r� x� t j j j | � D]v \ } } } | j | � x* | D]" } | j t j j | | � � qT Wx* | D]" } | j t j j | | � � q� Wq1 Wn | S( N( R\ R R R{ R R t os_walkRK R ( RA R t rootR~ R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _processM s %
'u fileu nameu __id__u funu recursei u Keep from {0}: {1}u' Files to keep from required states: {0}(
R\ t
isinstanceRF t __lowstate__R R R{ Rv RH RI R* RL RK ( RA t requireR� Rz R� RV t compt required_filest lowt fnt funt fkeep( ( R� R� R� R� s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _gen_keep_files) s4 %
(
c C@ sj t } d } t j j | � s6 t } d j | � } n* t j j | � s` t } d j | � } n | | f S( Nu u* Specified file {0} is not an absolute pathu {0}: file not found( R8 R R t isabsR4 R* t exists( RA R t msg( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_filet s c C@ s� t � } | j | � t | t � r� x� | D]� } t j j | � sJ q, n t j j t j j | � � } | j | � xc t r� t j j t j j
| � � } | j | � t j j | � \ } } | j t j
� sx Pqx qx Wq, Wn | S( uX
Compile a list of valid keep files (and directories).
Used by _clean_dir()
( R\ RK R� RF R R R� t normcaseRw R8 Rc t
splitdrivet lstripR2 ( R� RV t real_keepRm t driveR ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _find_keep_files� s
c @ s� t j j � � � t � | � � t � � � � � � f d � } x\ t j j j � � D]E \ } } } x3 t j | | � D] } | t j j
| | � � qz WqX Wt � � S( u�
Clean out all of the files and directories in a directory (root) while
preserving the files in a list (keep) and part of exclude_pat
c @ s� | � k r� t j j j t j j | � � d � � s: d S� j | � t d s� y t j
| � Wq� t k
r� t d | � q� Xq� n d S( Nu testu file.remove(
R R RD RE R R R9 R5 RK R RJ t OSErrorR) ( t nfn( RT R� t removedR� ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _delete_not_kept� s
( R R R� R� R\ R R R� t itertoolst chainR RF ( R� RV RT R� t rootsR~ R RA ( ( RT R� R� R� s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt
_clean_dir� s %!c C@ s t | d <| | d <| S( Nu resultu comment( R4 ( R t err_msg( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _error� s
c
@ s� i } | s | r] t t � | � � } i }
x- | D]" } | d | d f |
| d <q4 Wn | r|y t | � } Wn, t t f k
r� } t d j | � | f SXd | k r� d } n d | k r� d } n d | k r� d } d } n d | k } d | k } xz| D]o\ � } } | rx� | D]� } i } t j j
� | � } t d
| d |
� } | d k r�| | j d � k r�| | d <n | d k r�| | j d � k r�| | d <n | d k rt
j j j | � t
j j j | j d � � k r| | d <n | r"| | | <q"q"Wn | rxQ | D]F } t j j
� | � } t | | | | |
� } | r(| | | <q(q(WqqWn t � | | | |
� } | r�| | � <n | r<t � | |
� � � � � � f d � } xb | D]W \ � } } x! | D] } | j | | � � q�Wx! | D] } | j | | � � qWq�Wn t j j � � sbi d d
6| � <n | r�d g } xN | D]F } x= t j | | � D]( \ } } | j d j | | | � � q�WqxWd d j
| � | f St d j � � | f S( u;
Check what changes need to be made on a directory
i i i u {0}u useru groupu modeu ignore_filesu ignore_dirsu
file.statsc @ si t j j � | � } | � k r% i St j j j t j j | � � d � � sS i Si i d d 6| 6Sd S( Nu Removed due to cleanu removed( R R R R R RD RE R9 R5 ( t fnameR ( RT RV RA R� ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_changes� s u newu directoryu% The following files will be changed:
u {0}: {1} - {2}
u u) The directory {0} is in the correct stateN( RF t _depth_limited_walkt _get_recurse_sett TypeErrort
ValueErrorR4 R* R5 R R R R) R| R R R t normalize_modet _check_dir_metaR� RL R{ R RC t appendR8 ( RA R+ R, t recurset dir_modet file_modet cleanR� RT t max_deptht follow_symlinkst changest walk_lR� t it recurse_sett exct check_filest
check_dirsR~ R R� t fchangeR t statst name_R� t commentsRm t keyt val( ( RT RV RA R� s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_directory� sz
#
!
!
?
$c C@ s� i } t j j | � s/ i i d d 6| 6} n=| d k r� t j j j | � } t j j j | � } t j j j | � } | | k s� | | d <q� n t j j j
| � }
| d k r�x<| D]1} y t j j j | � Wn t k
r� q� n Xg } t
| | d t j � rIt j j j | | | | d � s�| | d } q�nR xO | | d D]? }
t j j j | | |
d t �sX| j | | d � qXqXW| r�d | k r�i | d <n | | d k r�i | d | <n | | d | d <n d | | k r d } n | | d } | |
k r� t j j j | � } t j j j � j d | } t j j j � j d | } d
|
| k r�|
| d
d | k s�d | k r�i | d <n | | d k r�i | d | <n | | d | d <q�q�q� q� Wn | d k rGxB| D]7} y t j j j | � Wn t k
r<q n Xg } t
| | d t j � r�t j j j | | | | d d � s�| | d } q�nU xR | | d D]B }
t j j j | | |
d d t �s�| j | | d � q�q�W| rAd
| k r i | d
<n | | d
k r,i | d
| <n | | d
| d <n d | | k rZd } n | | d } | |
k r t j j j | � } t j j j � j d | } t j j j � j d | } d |
| k r@|
| d d | k s=d
| k ri | d
<n | | d
k r%i | d
| <n | | d
| d <q=q@q q Wn | d k r~| t j j j | � k s~| | d <q~n | rlx� |
D]� } | | k r�d
|
| k r�|
| d
d r�d | k r�i | d <n | d j i |
| | 6� q�n | | k r�d |
| k re|
| d d red | k rCi | d <n | d j i |
| | 6� qeq�q�Wn | r�d d j | � | f St d j | � | f S( u;
Check what changes need to be made on a directory
u newu directoryu owneru permst exactu grant_permsu
applies_tou this_folder_subfolders_filesu fileu grantu
applies tou denyu
deny_permsu inheritanceu inheritedu remove_permsu# The directory "{0}" will be changedu) The directory {0} is in the correct stateN( R R R{ R5 R R t win_daclt get_ownert
win_functionst get_sid_from_namet get_permissionst get_nameR R� R t string_typest has_permissionR4 R� t flagst ace_propt get_inheritanceRL R* R8 ( RA t win_ownert win_permst win_deny_permst win_inheritancet win_perms_resetR� t
current_ownert current_owner_sidt expected_owner_sidt permsR+ t grant_permst permt
applies_tot at_flagt applies_to_textt
deny_permst user_name( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_directory_win s�
"
"
#
" #
)c C@ s! y t d | d | � } Wn t k
r3 i } n Xi } | sN d | d <| S| d k r� | | d k r� | | j d � k r� | | d <n | d k r� | | d k r� | | j d � k r� | | d <n t j j j | d � } t j j j | � } | d k r | | k r | | d <n | S(
u1
Check the changes in directory metadata
u
file.statsu newu directoryu useru uidu groupu gidu modeN( R) R5 R R| R R R R� ( RA R+ R, t modeR� R� R� t smode( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� � s*
c C@ s i d d 6d d 6i | d 6d 6} t j j | � sJ d j | � | d <n� t d | d t �} | d k r� t j | � t j | d � k s� | d k r� t j | � t j | d
� k r� d j | � | d <i | d 6| d <n t | d <d
j | � | d <| S( u?
Check to see if a file needs to be updated or created
u resultu u commentu newu changesu File {0} is set to be createdu
file.statsR� u atimeu mtimeu# Times set to be updated on file {0}u touchedu) File {0} exists and has the correct timesN(
R5 R R R� R* R) R4 R t text_typeR8 ( RA t atimet mtimeR R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_touch� s " "
c C@ s_ t j j j � r1 t j j j | � } | | f St d | d t �t d | d t �f Sd S( Nu
file.get_userR� u file.get_group( R R t platformt
is_windowsR� R� R) R4 ( R t owner( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _get_symlink_ownership� s
c C@ sH t | � \ } } t j j j � r. | | k S| | k oC | | k Sd S( uM
Check if the symlink ownership matches the specified user and group
N( R� R R R� R� ( R R+ R, R� t cur_usert cur_group( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_symlink_ownership� s
c C@ s� t j j j � rC y t j j j | | � Wqo t k
r? qo Xn, y t d | | | � Wn t k
rn n Xt | | | | � S( u\
Set the ownership of a symlink and return a boolean indicating
success/failure
u file.lchown(
R R R� R� R� t set_ownerR R) R� R� ( R R+ R, R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _set_symlink_ownership� s
c C@ sJ i } t j j | � rM t d | � rM | | d <d
d j | | � | f St d | � rt d | � | k r� | | d <d
d j | | � | f St } d j | � } t | | | | � sd
} d j t | � � | d <| d
j | | t | � � 7} n | | | f Sn5 | r0d
d j | | � | f St d j | � | f Sd
S( u$
Check the symlink function
u file.is_linku newu& Symlink {0} to {1} is set for creationu
file.readlinku changeu+ Link {0} target is set to be changed to {1}u The symlink {0} is presentu {0}:{1}u ownershipuK , but the ownership of the symlink would be changed from {2}:{3} to {0}:{1}uX The file or directory {0} is set for removal to make way for a new symlink targeting {1}uT File or directory exists where the symlink {0} should be. Did you mean to use force?N(
R R R� R) R5 R* R8 R� R� R4 ( RA t targett forceR+ R, R� R� t resultR� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _symlink_check s4 $
c C@ s/ | r
| Sd | k r+ t j d � | d S| S( u�
Convert owner to user, since other config management tools use owner,
no need to punish people coming from other systems.
PLEASE DO NOT DOCUMENT THIS! WE USE USER, NOT OWNER!!!!
u owneruB Use of argument owner found, "owner" is invalid, please use "user"( RH t warning( Rh R+ ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _test_owner3 s c
C@ s� | d k r g } n | d k r* g } n | rC | rC t d g f S| r\ | r\ t d g f S| rx t d | | f g f St d t t | | t | � � � f S( ub
Silly little function to give us a standard tuple list for sources and
source_hashes
u) source and sources are mutually exclusiveu4 source_hash and source_hashes are mutually exclusiveu N( R5 R4 R8 RF R t len( Re t source_hasht sourcest
source_hashes( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _unify_sources_and_hashesE s
u jinjac K@ s� i d d 6i d 6t d 6d d 6g d 6} | d k rB t | d � Sg } xt| D]l\ } } | rg | n i } | r� | j | � n t d | d d
| d t d | | �}
d
} t j | j |
| � � |
r�d } t j
j j |
d � �7 }
|
j
� } t j
j j | � } | j t � } Wd QX| sod } t j | j |
| � � | | d <t | | j |
| � � S| j d j | � � qO d j | � } t j | � | | d <t | | � SqO W| | d <| S( u�
Iterate a list of sources and process them as templates.
Returns a list of 'chunks' containing the rendered templates.
u _get_template_textsu nameu changesu resultu u commentu datau1 _get_template_texts called with empty source_listu cp.get_templatet templateR[ t contextu/ cp.get_template returned {0} (Called with: {1})u rbNu/ Failed to read rendered template file {0} ({1})u Failed to load template file {0}( R8 R5 R� RL R) R_ RH RI R* R R R R t readRD t
to_unicodet
splitlinesR� R ( t source_listR� t defaultsR� Rh R t txtlRe R� t tmpctxt rndrd_templ_fnR� t tmplinest fp_( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _get_template_texts` sP
c C@ s� t | t j � r3 t j j j | d | �g } n� t | t j � rQ | g } n� t | t � r� t | t � r� g } x[ | D]> } t | t j � r� | j
| � q} | j
t j | � � q} Wn t j | � g } | S( u-
ensure ``arg`` is a list of strings
t encoding( R� R t binary_typeR R RD R� R� R R R� R� ( t argR R t item( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _validate_str_list� s !
c C@ s t d | d t �S( Nu
file.get_userR� ( R) R4 ( R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _get_shortcut_ownership� s c C@ s t | � } | | k S( uD
Check if the shortcut ownership matches the specified user
( R ( R R+ R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _check_shortcut_ownership� s c C@ s6 y t d | | � Wn t k
r( n Xt | | � S( u]
Set the ownership of a shortcut and return a boolean indicating
success/failure
u file.lchown( R) R� R ( R R+ ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _set_shortcut_ownership� s
c C@ s+ i } t j j | � s; | | d <d d j | | � | f St j j | � r�t j j j � � t
j j d � } Wd QX| j
| � }
|
j j � | j � k g } | d k r� | j |
j | k � n | d k r� | j |
j j � | j � k � n | d k r | j |
j | k � n | d k rQ| j |
j j � | j � k � n t | � s�| | d <d d j | | � | f St } d j | � }
t | | � s�d } d j t | � � | d <|
d
j | t | � � 7}
n | |
| f Sn5 | rd d j | | � | f St d j | � | f Sd S(
u%
Check the shortcut function
u newu+ Shortcut "{0}" to "{1}" is set for creationu
WScript.ShellNu changeu3 Shortcut "{0}" target is set to be changed to "{1}"u The shortcut "{0}" is presentu {0}u ownershipuD , but the ownership of the shortcut would be changed from {1} to {0}u] The link or directory "{0}" is set for removal to make way for a new shortcut targeting "{1}"uW Link or directory exists where the shortcut "{0}" should be. Did you mean to use force?( R R R� R5 R* t isfileR R t winapit Comt win32comt clientt Dispatcht CreateShortcutt
TargetPatht lowerR� t Argumentst WorkingDirectoryt Descriptiont IconLocationt allR8 R R R4 ( RA R� t argumentst working_dirt descriptiont
icon_locationR� R+ R� t shellt scutt state_checksR� R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _shortcut_check� sP
c
C@ s� t j j j � r� t j j | � \ } } t j j | � sK t | � � n | rW | n | } t d d | d | d | d | d | � St d d | d | d | d | � Sd
S( u�
Helper function for creating directories when the ``makedirs`` option is set
to ``True``. Handles Unix and Windows based systems
.. versionadded:: 2017.7.8
Args:
name (str): The directory path to create
user (str): The linux user to own the directory
group (str): The linux group to own the directory
dir_mode (str): The linux mode to apply to the directory
win_owner (str): The Windows user to own the directory
win_perms (dict): A dictionary of grant permissions for Windows
win_deny_perms (dict): A dictionary of deny permissions for Windows
win_inheritance (bool): True to inherit permissions on Windows
Returns:
bool: True if successful, otherwise False on Windows
str: Error messages on failure on Linux
None: On successful creation on Linux
Raises:
CommandExecutionError: If the drive is not mounted on Windows
u
file.makedirsR R� R� R� t inheritanceR+ R, R� N(
R R R� R� R R R� R{ R R) (
RA R+ R, R� R� R� R� R� R� R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _makedirs s c K@ s� t j j | � } t j j j | � } t | d | �} i | d 6i d 6t d 6d d 6}
| sn t |
d � S| d> k r� t d } n t j j j
� rt d | � s� t d
� } | s� d } q� n | d> k r� | r� | n d> } n | d> k rt j d j | � � n | } n | d> k rLt d
t d | � j d d � � } n g } t j j j
� rdy t j j j | � Wn) t k
r�} | j d j | � � n X| rxT | D]I } y t j j j | � Wq�t k
r�} | j d j | � � q�Xq�Wn |
r�xT |
D]I } y t j j j | � Wqt k
rY} | j d j | � � qXqWq�nj t d | � } t d | � } | d k r�| j d j | � � n | d k r�| j d j | � � n t j j | � s�| j d j | � � n | r:d j | � } t | � d k r-| d 7} n t |
| � St | | | | | | � \ } } } t j j t j j | � � si| rt d r�| d j t j j | � � 7} qfy; t d | d | d | d | d | d | d |
d | � Wqft k
r} t |
d! j | j � � SXqit d rD| d" j t j j | � � 7} qit |
d# j t j j | � � � Sn t d r�| |
d <| |
d <| |
d <|
St d$ | � r$t j j t d% | � � t j j | � k r�t j | � q�t! | | | | � r?t j j j
� r#d& j | | � |
d <q d' j | | | � |
d <n� t" | | | | � r�t j j j
� r�d( j | | � |
d <| |
d d) <q d* j | | | � |
d <d+ j | | � |
d d) <nZ t# |
d <t j j j
� r�|
d c d, j | | � 7<n |
d c d- j | | | � 7<|
Sn�t j j$ | � sHt j j | � r�| d> k rvt j j | � s�| t j j% | � k r�t j j t j j t j j | � � | � } q�t |
d. j | � � Sn t j j& | � r | s�t |
d/ j | | | � � St d0 | � n y t d1 | | � Wq�t' k
rr} i |
d <t j( d2 | | d3 t �t |
d4 j | | | � � SXq�| r�t d$ | � r�t d0 | � d5 |
d d6 <q�t d0 | � q�t j j$ | � r�t |
d7 j | � � St |
d8 j | � � Sn t j j) | � s�y t d9 | | � Wn7 t* k
r]} t# |
d <d: j | | | � |
d <|
SXd; j | | � |
d <| |
d d< <t! | | | | � s�t" | | | | � s�t# |
d <|
d c d= j | | � 7<q�q�n |
S(? uo
Create a symbolic link (symlink, soft link)
If the file already exists and is a symlink pointing to any location other
than the specified target, the symlink will be replaced. If the symlink is
a regular file or directory then the state will return False. If the
regular file or directory is desired to be replaced with a symlink pass
force: True, if it is to be renamed, pass a backupname.
name
The location of the symlink to create
target
The location that the symlink points to
force
If the name of the symlink exists and is not a symlink and
force is set to False, the state will fail. If force is set to
True, the file or directory in the way of the symlink file
will be deleted to make room for the symlink, unless
backupname is set, when it will be renamed
backupname
If the name of the symlink exists and is not a symlink, it will be
renamed to the backupname. If the backupname already
exists and force is False, the state will fail. Otherwise, the
backupname will be removed first.
An absolute path OR a basename file/directory name must be provided.
The latter will be placed relative to the symlink destination's parent
directory.
makedirs
If the location of the symlink does not already have a parent directory
then the state will fail, setting makedirs to True will allow Salt to
create the parent directory
user
The user to own the file, this defaults to the user salt is running as
on the minion
group
The group ownership set for the file, this defaults to the group salt
is running as on the minion. On Windows, this is ignored
mode
The permissions to set on this file, aka 644, 0775, 4664. Not supported
on Windows.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
win_owner : None
The owner of the symlink and directories if ``makedirs`` is True. If
this is not passed, ``user`` will be used. If ``user`` is not passed,
the account under which Salt is running will be used.
.. versionadded:: 2017.7.7
win_perms : None
A dictionary containing permissions to grant
.. versionadded:: 2017.7.7
win_deny_perms : None
A dictionary containing permissions to deny
.. versionadded:: 2017.7.7
win_inheritance : None
True to inherit permissions from parent, otherwise False
.. versionadded:: 2017.7.7
R+ u nameu changesu resultu u commentu! Must provide name to file.symlinku useru user.infou user.currentu SYSTEMu� The group argument for {0} has been ignored as this is a Windows system. Please use the `win_*` parameters to set permissions in Windows.u file.gid_to_groupu gidi u User {0} does not existu file.user_to_uidu file.group_to_gidu Group {0} does not existu* Specified file {0} is not an absolute pathu . i u .u testu
{0} will be createdRA R, R� R� R� R� R� u Drive {0} is not mappedu)
Directory {0} for symlink is not presentu( Directory {0} for symlink is not presentu file.is_linku
file.readlinku' Symlink {0} is present and owned by {1}u+ Symlink {0} is present and owned by {1}:{2}u# Set ownership of symlink {0} to {1}u ownershipu' Set ownership of symlink {0} to {1}:{2}u {0}:{1}u- Failed to set ownership of symlink {0} to {1}u1 Failed to set ownership of symlink {0} to {1}:{2}u7 Backupname must be an absolute path or a file name: {0}uH Symlink & backup dest exists and Force not set. {0} -> {1} - backup: {2}u file.removeu file.moveu# Encountered error renaming %s to %st exc_infou+ Unable to rename {0} to backup {1} -> : {2}u Symlink was forcibly replacedu forcedu+ File exists where the symlink {0} should beu0 Directory exists where the symlink {0} should beu file.symlinku, Unable to create new symlink {0} -> {1}: {2}u Created new symlink {0} -> {1}u newu, , but was unable to set ownership to {0}:{1}N(+ R R t
expanduserR R R R� R� R8 R� R5 R R� R� R) RH R� R* R| R� R� R R� R� R R� R� R{ Rc R( t messageR= RJ R� R� R4 R t basenamet lexistst ExceptionRI R� R� ( RA R� R� t
backupnamet makedirsR+ R, R� R� R� R� R� Rh R t preflight_errorsR� t
name_checkR. R/ R� t presultt pcommentt pchanges( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt symlink7 sT W
"
!
$
"
.
$
c K@ sc t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � St j j | � so t | d j | � � S| d k r� t | d � St j j | � s� t j j | � rqt d
r� d | d <| | d d <d j | � | d <| Sy` t j j
j � rt d
| d t �n t d
| � d j | � | d <| | d d <| SWqLt k
rm} t | d j | � � SXn� t j j | � rLt d
r�d | d <| | d d <d j | � | d <| Sy` t j j
j � r�t d
| d t �n t d
| � d j | � | d <| | d d <| SWqLt t f k
rHt | d j | � � SXn d j | � | d <| S( u!
Make sure that the named file or directory is absent. If it exists, it will
be deleted. This will work to reverse any of the functions in the file
state module. If a directory is supplied, it will be recursively deleted.
name
The path which should be deleted
u nameu changesu resultu u commentu Must provide name to file.absentu* Specified file {0} is not an absolute pathu /u Refusing to make "/" absentu testu removedu File {0} is set for removalu file.removeR� u Removed file {0}u {0}u Directory {0} is set for removalu Removed directory {0}u Failed to remove directory {0}u File {0} is not presentN( R R R* R8 R� R� R* R Rt R R5 R R R� R� R) R R{ R� R ( RA Rh R R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt absentz sX
$
c @ sT t j j | � } i | d 6i d 6i d 6t d 6d d 6} t j j | � sc t | d j | � � St j j | � s� t | d j | � � Sg } t j � } | d k r� d g } n g � x$ | D] } � j t j
| � � q� W� f d
� }
xPt j d | d t � D]6\ } } }
x$|
| D]} d
} d
} t } t j j | | � } t j j | � r�t | t j t j | � j � � } nq | | k r�t | t j t j j | � � � } | } n7 t | t j t j j | � � � } t j j | � } | | k s| j | k r$|
d | � r$| r$| j | � q$q$Wq
W| r=t d r�d | d <d j | � | d <i | d 6| d <| Sg | d d <ya xZ | D]R } t j j j � r�t d | d t �n t d | � | d d j | � q�WWn& t k
r } t | d j | � � SXd j t | � | � | d <n d j | � | d <| S( u�
Remove unwanted files based on specific criteria. Multiple criteria
are OR’d together, so a file that is too large but is not old enough
will still get tidied.
If neither age nor size is given all files which match a pattern in
matches will be removed.
name
The directory tree that should be tidied
age
Maximum age in days after which files are considered for removal
matches
List of regular expressions to restrict what gets removed. Default: ['.*']
rmdirs
Whether or not it's allowed to remove directories
size
Maximum allowed file size. Files greater or equal to this size are
removed. Doesn't apply to directories or symbolic links
.. code-block:: yaml
cleanup:
file.tidied:
- name: /tmp/salt_test
- rmdirs: True
- matches:
- foo
- b.*r
u nameu changesu pchangesu resultu u commentu* Specified file {0} is not an absolute pathu) {0} does not exist or is not a directory.u .*c @ s( x! � D] } | j | � r t Sq Wt S( N( t matchR8 R4 ( RA t prog( t progs( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _matches� s
t topt topdowni RA u testu {0} is set for tidyu removedu file.removeR� u {0}u3 Removed {0} files or directories from directory {1}u$ Nothing to remove from directory {0}N(! R R R* R8 R� R� R* R{ R t todayR5 R� t ret compilet walkR4 R Rt t abst
fromtimestampt lstatt st_atimet getatimet getsizet daysR R R R� R� R) R R� ( RA t aget matchest rmdirst sizeRh R t todeleteR> t regexR; R� R~ R t elemt myaget mysizet deletemeR R� ( ( R: s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt tidied� sf (
(( % %0
c K@ s� t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � St j j | � so t | d j | � � Sd j | � | d <| S( ui
Verify that the named file or directory is present or exists.
Ensures pre-requisites outside of Salt's purview
(e.g., keytabs, private keys, etc.) have been previously satisfied before
deployment.
This function does not create the file if it doesn't exist, it will return
an error.
name
Absolute path which must exist
u nameu changesu resultu u commentu Must provide name to file.existsu! Specified path {0} does not existu Path {0} exists( R R R* R8 R� R� R* ( RA Rh R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� 3 s
c K@ s� t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � St j j | � ro t | d j | � � Sd j | � | d <| S( u�
Verify that the named file or directory is missing, this returns True only
if the named file is missing but does not remove the file if it is present.
name
Absolute path which must NOT exist
u nameu changesu resultu u commentu! Must provide name to file.missingu Specified path {0} existsu Path {0} is missing( R R R* R8 R� R� R* ( RA Rh R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt missingP s
u u :u strictc$ = 3 K@ s� d |$ k r |$ j d � n t j j | � } i i d 6d d 6| d 6t d 6}% | rg t |% d � Sn | t k o� t j j j
� r� t |% d � Sn | t k o� t j j j
� r� t |% d � Sn y% | j � d
k }& |& r� t } n Wn t k
rt
}& n Xt j j j | � } t g | | | f D] }' |' t k rB|' ^ q*� }( | oZ|( d k rmt |% d � Sn> |& o||( d k r�t |% d
� Sn |( d k r�t |% d � Sn | o�|( d k o�|
r�t
}
t j d j | � � n d |$ k r |% j d g � j d � n | t k r�t | t � r�g }) xY | D]Q }* t d |* t d | �}+ |+ t k rwt |% d j |* � � Sn |) j |+ � q3Wt j j |) � }, n> t d | t d | �}, |, t k r�t |% d j | � � Sn n� | t k r�t | t � rpg }) xY | D]Q }- t d |- t d | �}+ |+ t k rJt |% d j |+ � � Sn |) j |+ � qWt j j |) � }, n> t d | t d | �}, |, t k r�t |% d j | � � Sn n | t k r�| }, n t }, |, t k r�| o�|, r5| r�d j | � }. n | rd j | � }. n d }. t |% d j |. � � Sn y� t |, d | �}/ |/ rat |% d � Sn d } xH |/ D]@ }0 x7 |0 j � D]) }1 | |1 j d � j d � t j 7} q�WqnW| o�| j t j � r�| t j 7} n Wn- t k
r | rt |% d! � Sn |, } n X| r�t d" | d# | d$ | d% | d& t! �} t | t" j# � r�d | k rj| d |% d <n
t
|% d <d | k r�| d |% d <n
d' |% d <|% Sn n n t$ |$ d( | �} t j j j
� r| t k r�| r�| n t } n | t k rt j d) j | � � n | } n | rRt j j% | � rOd* j | � |% d <|% Sn n t& | | � }2 |2 rwt |% |2 � Sn t j j' | � r�t |% d+ j | � � Sn t j j( | � r�d, j | � |% d <t
|% d <|% Sn | t k r�i } n t | t) � rt |% d- � Sn | o!t | t) � r4t |% d. � Sn |
oJt j j* | � rdi }3 t j j j
� r�t d/ d0 | d1 |% d2 | d3 | d4 |! d5 |" d6 |# � }% n( t d/ | |% | | | | | � \ }% }3 t+ d7 r2t |3 t) � o�d8 |3 k o�| |3 d8 k r d9 j | | |3 d8 � |% d <n d: j | � |% d <n+ |% d oD|% d r]d; j | � |% d <n |% Sn t, � \ }4 }5 | |4 k r�| r�i } n |4 | | d< <n y�t+ d7 r:
d= t k r� t d= | | | | | | | | | | | t! | | |& |$ � |% d <t j j j
� r� y; t d/ d0 | d1 |% d2 | d3 | d4 |! d5 |" d6 |# � }% Wn6 t- k
r }6 |6 j. j/ d> � r| | |% d d? <n n Xn n t |% d t0 � r� |% d \ |% d <|% d <n |% d r
t |% d <d@ j | � |% d <|% d c dA 7<dB |% d k o� | r
dC |% d dB <n n t |% d <dD j | � |% d <|% Sn t dE | | t! � \ } } Wn4 t- k
r�
}6 t
|% d <dF j |6 � |% d <|% Sn XyD t dG | | | | | | | | | t! | | | |$ �
\ }7 }8 }9 WnF t1 k
r }6 i |% d <t j2 t3 j4 � � t |% dF j |6 � � Sn Xt }: | r�
t j j j5 dH | dI | � }: t dJ | � r� y t dK | |: � Wn/ t1 k
r� }6 t |% dL j | |: |6 � � Sn Xn yw t dM |: |7 |% | |8 | | | | t! | |
| | | | | | |& dN | dO | dP |! dQ |" dR |# d | dS | |$ �}% Wn� t1 k
r� }6 i |% d <t j2 t3 j4 � � t j j j6 |: � | r� |7 o~ | o~ t7 | � j8 dT k r� t dU | t! � }7 n |7 r� t j j j6 |7 � n n t |% dV j |6 � � Sn X|% d rp
i i d 6d d 6| d 6t d 6}% i }; dW t9 k r
t9 dW |; dW <n t: | |: |; � }< t |< t) � rg
|% j; |< � t j j j6 |: � |% Sn |: }7 n" i i d 6d d 6| d 6t d 6}% n |9 o�
| t k r�
t |% |9 � Sn@z� yu t dM | |7 |% | |8 | | | | t! | |
| | | | | | |& dN | dO | dP |! dQ |" dR |# d | dS | |$ �SWnF t1 k
rw}6 i |% d <t j2 t3 j4 � � t |% dF j |6 � � Sn XWdX |: r�t j j j6 |: � n | r�|7 o�| o�t7 | � j8 dT k r�t dU | t! � }7 n |7 r�t j j j6 |7 � n n XdX S(Y uAT
Manage a given file, this function allows for a file to be downloaded from
the salt master and potentially run through a templating system.
name
The location of the file to manage, as an absolute path.
source
The source file to download to the minion, this source file can be
hosted on either the salt master server (``salt://``), the salt minion
local file system (``/``), or on an HTTP or FTP server (``http(s)://``,
``ftp://``).
Both HTTPS and HTTP are supported as well as downloading directly
from Amazon S3 compatible URLs with both pre-configured and automatic
IAM credentials. (see s3.get state documentation)
File retrieval from Openstack Swift object storage is supported via
swift://container/object_path URLs, see swift.get documentation.
For files hosted on the salt file server, if the file is located on
the master in the directory named spam, and is called eggs, the source
string is salt://spam/eggs. If source is left blank or None
(use ~ in YAML), the file will be created as an empty file and
the content will not be managed. This is also the case when a file
already exists and the source is undefined; the contents of the file
will not be changed or managed.
If the file is hosted on a HTTP or FTP server then the source_hash
argument is also required.
A list of sources can also be passed in to provide a default source and
a set of fallbacks. The first source in the list that is found to exist
will be used and subsequent entries in the list will be ignored. Source
list functionality only supports local files and remote files hosted on
the salt master server or retrievable via HTTP, HTTPS, or FTP.
.. code-block:: yaml
file_override_example:
file.managed:
- source:
- salt://file_that_does_not_exist
- salt://file_that_exists
source_hash
This can be one of the following:
1. a source hash string
2. the URI of a file that contains source hash strings
The function accepts the first encountered long unbroken alphanumeric
string of correct length as a valid hash, in order from most secure to
least secure:
.. code-block:: text
Type Length
====== ======
sha512 128
sha384 96
sha256 64
sha224 56
sha1 40
md5 32
**Using a Source Hash File**
The file can contain several checksums for several files. Each line
must contain both the file name and the hash. If no file name is
matched, the first hash encountered will be used, otherwise the most
secure hash with the correct source file name will be used.
When using a source hash file the source_hash argument needs to be a
url, the standard download urls are supported, ftp, http, salt etc:
Example:
.. code-block:: yaml
tomdroid-src-0.7.3.tar.gz:
file.managed:
- name: /tmp/tomdroid-src-0.7.3.tar.gz
- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz
- source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash
The following lines are all supported formats:
.. code-block:: text
/etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27
sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf
ead48423703509d37c4a90e6a0d53e143b6fc268
Debian file type ``*.dsc`` files are also supported.
**Inserting the Source Hash in the SLS Data**
The source_hash can be specified as a simple checksum, like so:
.. code-block:: yaml
tomdroid-src-0.7.3.tar.gz:
file.managed:
- name: /tmp/tomdroid-src-0.7.3.tar.gz
- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz
- source_hash: 79eef25f9b0b2c642c62b7f737d4f53f
.. note::
Releases prior to 2016.11.0 must also include the hash type, like
in the below example:
.. code-block:: yaml
tomdroid-src-0.7.3.tar.gz:
file.managed:
- name: /tmp/tomdroid-src-0.7.3.tar.gz
- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz
- source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f
Known issues:
If the remote server URL has the hash file as an apparent
sub-directory of the source file, the module will discover that it
has already cached a directory where a file should be cached. For
example:
.. code-block:: yaml
tomdroid-src-0.7.3.tar.gz:
file.managed:
- name: /tmp/tomdroid-src-0.7.3.tar.gz
- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz
- source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5
source_hash_name
When ``source_hash`` refers to a hash file, Salt will try to find the
correct hash by matching the filename/URI associated with that hash. By
default, Salt will look for the filename being managed. When managing a
file at path ``/tmp/foo.txt``, then the following line in a hash file
would match:
.. code-block:: text
acbd18db4cc2f85cedef654fccc4a4d8 foo.txt
However, sometimes a hash file will include multiple similar paths:
.. code-block:: text
37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt
acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt
73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt
In cases like this, Salt may match the incorrect hash. This argument
can be used to tell Salt which filename to match, to ensure that the
correct hash is identified. For example:
.. code-block:: yaml
/tmp/foo.txt:
file.managed:
- source: https://mydomain.tld/dir2/foo.txt
- source_hash: https://mydomain.tld/hashes
- source_hash_name: ./dir2/foo.txt
.. note::
This argument must contain the full filename entry from the
checksum file, as this argument is meant to disambiguate matches
for multiple files that have the same basename. So, in the
example above, simply using ``foo.txt`` would not match.
.. versionadded:: 2016.3.5
keep_source : True
Set to ``False`` to discard the cached copy of the source file once the
state completes. This can be useful for larger files to keep them from
taking up space in minion cache. However, keep in mind that discarding
the source file will result in the state needing to re-download the
source file if the state is run again.
.. versionadded:: 2017.7.3
user
The user to own the file, this defaults to the user salt is running as
on the minion
group
The group ownership set for the file, this defaults to the group salt
is running as on the minion. On Windows, this is ignored
mode
The permissions to set on this file, e.g. ``644``, ``0775``, or
``4664``.
The default mode for new files and directories corresponds to the
umask of the salt process. The mode of existing files and directories
will only be changed if ``mode`` is specified.
.. note::
This option is **not** supported on Windows.
.. versionchanged:: 2016.11.0
This option can be set to ``keep``, and Salt will keep the mode
from the Salt fileserver. This is only supported when the
``source`` URL begins with ``salt://``, or for files local to the
minion. Because the ``source`` option cannot be used with any of
the ``contents`` options, setting the ``mode`` to ``keep`` is also
incompatible with the ``contents`` options.
.. note:: keep does not work with salt-ssh.
As a consequence of how the files are transferred to the minion, and
the inability to connect back to the master with salt-ssh, salt is
unable to stat the file as it exists on the fileserver and thus
cannot mirror the mode on the salt-ssh minion
attrs
The attributes to have on this file, e.g. ``a``, ``i``. The attributes
can be any or a combination of the following characters:
``aAcCdDeijPsStTu``.
.. note::
This option is **not** supported on Windows.
.. versionadded:: 2018.3.0
template
If this setting is applied, the named templating engine will be used to
render the downloaded file. The following templates are supported:
- :mod:`cheetah<salt.renderers.cheetah>`
- :mod:`genshi<salt.renderers.genshi>`
- :mod:`jinja<salt.renderers.jinja>`
- :mod:`mako<salt.renderers.mako>`
- :mod:`py<salt.renderers.py>`
- :mod:`wempy<salt.renderers.wempy>`
makedirs : False
If set to ``True``, then the parent directories will be created to
facilitate the creation of the named file. If ``False``, and the parent
directory of the destination file doesn't exist, the state will fail.
dir_mode
If directories are to be created, passing this option specifies the
permissions for those directories. If this is not set, directories
will be assigned permissions by adding the execute bit to the mode of
the files.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
replace : True
If set to ``False`` and the file already exists, the file will not be
modified even if changes would otherwise be made. Permissions and
ownership will still be enforced, however.
context
Overrides default context variables passed to the template.
defaults
Default context passed to the template.
backup
Overrides the default backup mode for this specific file. See
:ref:`backup_mode documentation <file-state-backups>` for more details.
show_changes
Output a unified diff of the old file and the new file. If ``False``
return a boolean if any changes were made.
create : True
If set to ``False``, then the file will only be managed if the file
already exists on the system.
contents
Specify the contents of the file. Cannot be used in combination with
``source``. Ignores hashes and does not use a templating engine.
This value can be either a single string, a multiline YAML string or a
list of strings. If a list of strings, then the strings will be joined
together with newlines in the resulting file. For example, the below
two example states would result in identical file contents:
.. code-block:: yaml
/path/to/file1:
file.managed:
- contents:
- This is line 1
- This is line 2
/path/to/file2:
file.managed:
- contents: |
This is line 1
This is line 2
contents_pillar
.. versionadded:: 0.17.0
.. versionchanged:: 2016.11.0
contents_pillar can also be a list, and the pillars will be
concatinated together to form one file.
Operates like ``contents``, but draws from a value stored in pillar,
using the pillar path syntax used in :mod:`pillar.get
<salt.modules.pillar.get>`. This is useful when the pillar value
contains newlines, as referencing a pillar variable using a jinja/mako
template can result in YAML formatting issues due to the newlines
causing indentation mismatches.
For example, the following could be used to deploy an SSH private key:
.. code-block:: yaml
/home/deployer/.ssh/id_rsa:
file.managed:
- user: deployer
- group: deployer
- mode: 600
- attrs: a
- contents_pillar: userdata:deployer:id_rsa
This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of
``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar
setup would be like so:
.. code-block:: yaml
userdata:
deployer:
id_rsa: |
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY
U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy
B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+
GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI
-----END RSA PRIVATE KEY-----
.. note::
The private key above is shortened to keep the example brief, but
shows how to do multiline string in YAML. The key is followed by a
pipe character, and the mutliline string is indented two more
spaces.
To avoid the hassle of creating an indented multiline YAML string,
the :mod:`file_tree external pillar <salt.pillar.file_tree>` can
be used instead. However, this will not work for binary files in
Salt releases before 2015.8.4.
contents_grains
.. versionadded:: 2014.7.0
Operates like ``contents``, but draws from a value stored in grains,
using the grains path syntax used in :mod:`grains.get
<salt.modules.grains.get>`. This functionality works similarly to
``contents_pillar``, but with grains.
For example, the following could be used to deploy a "message of the day"
file:
.. code-block:: yaml
write_motd:
file.managed:
- name: /etc/motd
- contents_grains: motd
This would populate ``/etc/motd`` file with the contents of the ``motd``
grain. The ``motd`` grain is not a default grain, and would need to be
set prior to running the state:
.. code-block:: bash
salt '*' grains.set motd 'Welcome! This system is managed by Salt.'
contents_newline : True
.. versionadded:: 2014.7.0
.. versionchanged:: 2015.8.4
This option is now ignored if the contents being deployed contain
binary data.
If ``True``, files managed using ``contents``, ``contents_pillar``, or
``contents_grains`` will have a newline added to the end of the file if
one is not present. Setting this option to ``False`` will omit this
final newline.
contents_delimiter
.. versionadded:: 2015.8.4
Can be used to specify an alternate delimiter for ``contents_pillar``
or ``contents_grains``. This delimiter will be passed through to
:py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get
<salt.modules.grains.get>` when retrieving the contents.
encoding
If specified, then the specified encoding will be used. Otherwise, the
file will be encoded using the system locale (usually UTF-8). See
https://docs.python.org/3/library/codecs.html#standard-encodings for
the list of available encodings.
.. versionadded:: 2017.7.0
encoding_errors : 'strict'
Error encoding scheme. Default is ```'strict'```.
See https://docs.python.org/2/library/codecs.html#codec-base-classes
for the list of available schemes.
.. versionadded:: 2017.7.0
allow_empty : True
.. versionadded:: 2015.8.4
If set to ``False``, then the state will fail if the contents specified
by ``contents_pillar`` or ``contents_grains`` are empty.
follow_symlinks : True
.. versionadded:: 2014.7.0
If the desired path is a symlink follow it and make changes to the
file to which the symlink points.
check_cmd
.. versionadded:: 2014.7.0
The specified command will be run with an appended argument of a
*temporary* file containing the new managed contents. If the command
exits with a zero status the new managed contents will be written to
the managed destination. If the command exits with a nonzero exit
code, the state will fail and no changes will be made to the file.
For example, the following could be used to verify sudoers before making
changes:
.. code-block:: yaml
/etc/sudoers:
file.managed:
- user: root
- group: root
- mode: 0440
- attrs: i
- source: salt://sudoers/files/sudoers.jinja
- template: jinja
- check_cmd: /usr/sbin/visudo -c -f
**NOTE**: This ``check_cmd`` functions differently than the requisite
``check_cmd``.
tmp_dir
Directory for temp file created by ``check_cmd``. Useful for checkers
dependent on config file location (e.g. daemons restricted to their
own config directories by an apparmor profile).
.. code-block:: yaml
/etc/dhcp/dhcpd.conf:
file.managed:
- user: root
- group: root
- mode: 0755
- tmp_dir: '/etc/dhcp'
- contents: "# Managed by Salt"
- check_cmd: dhcpd -t -cf
tmp_ext
Suffix for temp file created by ``check_cmd``. Useful for checkers
dependent on config file extension (e.g. the init-checkconf upstart
config checker).
.. code-block:: yaml
/etc/init/test.conf:
file.managed:
- user: root
- group: root
- mode: 0440
- tmp_ext: '.conf'
- contents:
- 'description "Salt Minion"'
- 'start on started mountall'
- 'stop on shutdown'
- 'respawn'
- 'exec salt-minion'
- check_cmd: init-checkconf -f
skip_verify : False
If ``True``, hash verification of remote file sources (``http://``,
``https://``, ``ftp://``) will be skipped, and the ``source_hash``
argument will be ignored.
.. versionadded:: 2016.3.0
win_owner : None
The owner of the directory. If this is not passed, user will be used. If
user is not passed, the account under which Salt is running will be
used.
.. versionadded:: 2017.7.0
win_perms : None
A dictionary containing permissions to grant and their propagation. For
example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a
single basic perm or a list of advanced perms. ``perms`` must be
specified. ``applies_to`` does not apply to file objects.
.. versionadded:: 2017.7.0
win_deny_perms : None
A dictionary containing permissions to deny and their propagation. For
example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a
single basic perm or a list of advanced perms. ``perms`` must be
specified. ``applies_to`` does not apply to file objects.
.. versionadded:: 2017.7.0
win_inheritance : True
True to inherit permissions from the parent directory, False not to
inherit permission.
.. versionadded:: 2017.7.0
win_perms_reset : False
If ``True`` the existing DACL will be cleared and replaced with the
settings defined in this function. If ``False``, new entries will be
appended to the existing DACL. Default is ``False``.
.. versionadded:: 2018.3.0
Here's an example using the above ``win_*`` parameters:
.. code-block:: yaml
create_config_file:
file.managed:
- name: C:\config\settings.cfg
- source: salt://settings.cfg
- win_owner: Administrators
- win_perms:
# Basic Permissions
dev_ops:
perms: full_control
# List of advanced permissions
appuser:
perms:
- read_attributes
- read_ea
- create_folders
- read_permissions
joe_snuffy:
perms: read
- win_deny_perms:
fred_snuffy:
perms: full_control
- win_inheritance: False
u envu changesu u commentu nameu resultu! Destination file name is requiredu- The 'mode' option is not supported on Windowsu. The 'attrs' option is not supported on Windowsu keepi u_ 'source' cannot be used in combination with 'contents', 'contents_pillar', or 'contents_grains'uh Mode preservation cannot be used in combination with 'contents', 'contents_pillar', or 'contents_grains'i uM Only one of 'contents', 'contents_pillar', and 'contents_grains' is permittedu
State for file: {0} - Neither 'source' nor 'contents' nor 'contents_pillar' nor 'contents_grains' was defined, yet 'replace' was set to 'True'. As there is no source to replace the file with, 'replace' has been set to 'False' to avoid reading the file unnecessarily.u file_modeu warningsu] The 'file_mode' argument will be ignored. Please use 'mode' instead to set file permissions.u
pillar.gett delimiteru Pillar {0} does not existu
grains.getu Grain {0} does not existu contents_pillar {0}u contents_grains {0}u
'contents'uh {0} value would result in empty contents. Set allow_empty to True to allow the managed file to be empty.R u� Contents specified by contents/contents_pillar/contents_grains is not a string or list of strings, and is not binary data. SLS is likely malformed.u
u
u� Contents specified by contents/contents_pillar/contents_grains appears to be binary data, and as will not be able to be treated as a Jinja template.u file.apply_template_on_contentsR� R� R R[ u) Error while applying template on contentsR+ u� The group argument for {0} has been ignored as this is a Windows system. Please use the `win_*` parameters to set permissions in Windows.u3 File {0} is not present and is not set for creationu* Specified file {0} is not an absolute pathu# Specified target {0} is a directoryu Context must be formed as a dictu! Defaults must be formed as a dictu file.check_permsR R R� R� R� R' t resetu testu lmodeuK File {0} will be updated with permissions {1} from its current state of {2}u File {0} not updatedu9 File {0} exists with proper permissions. No changes made.u accumulatoru file.check_managed_changesu Path not foundu newfileu! The file {0} is set to be changeduL
Note: No changes made, actual changes may
be different due to other states.u diffu <show_changes=False>u$ The file {0} is in the correct stateu file.source_listu Unable to manage file: {0}u file.get_managedt suffixt diru file.file_existsu file.copyu# Unable to copy file {0} to {1}: {2}u file.manage_fileR� R� R� R� R� t encoding_errorsu saltu cp.is_cachedu Unable to check_cmd file: {0}u shellN(< t popR R R* R8 R� R5 R R R� R� R t AttributeErrorR4 R R� R� RH R� R* t
setdefaultR� R� RF R) t __NOT_FOUNDt linesepR R
R t rstripR` t UnicodeDecodeErrorR_ R R� R� R R0 R� R{ t dictR� R R# R t strerrorRG t tupleR. RI t tracebackt
format_exct mkstempRJ t _urlparset schemet
__grains__t mod_run_check_cmdRL (= RA Re R� t source_hash_namet keep_sourceR+ R, R� t attrsR� R0 R� R� R> R t backupt show_changesRd t contentst tmp_dirt tmp_extt contents_pillart contents_grainst contents_newlinet contents_delimiterR RY t allow_emptyR� t check_cmdt skip_verifyR� R� R� R� R� Rh R t keep_modet xt contents_countt
list_contentst nextpt nextct use_contentst nextgt contents_idt validated_contentst partt linet u_checkt ret_permst
accum_dataR� R� t sfnt
source_sumt comment_t tmp_filenamet check_cmd_optst cret( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt managedh s� � � P
+
!
u useru groupu modeu ignore_filesu ignore_dirsc C@ s� | s
t � St | t � s+ t d � � n y t | � } Wn t k
rT d } n X| d k st t t � | k r� t d j d j d � t D� � � � � n d | k r� d | k r� t d � � n | S( u�
Converse *recurse* definition to a set of strings.
Raises TypeError or ValueError when *recurse* has wrong structure.
u- "recurse" must be formed as a list of stringsu# Types for "recurse" limited to {0}.u , c s@ s | ] } d j | � Vq d S( u "{0}"N( R* ( t .0t rtype( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pys <genexpr>� s u ignore_filesu ignore_dirsuU Must not specify "recurse" options "ignore_files" and "ignore_dirs" at the same time.N( R\ R� RF R� R5 t _RECURSE_TYPESR� R* R ( R� R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� � s
"c c@ s� x� t j j j | � D]| \ } } } | d k ro | j t j j � | j t j j � } | | k ro | 2qo n t j | � t
| � t
| � f Vq Wd S( u
Walk the directory tree under root up till reaching max_depth.
With max_depth=None (default), do not limit depth.
N( R R R R� R5 R7 R R2 R R� RF ( R< R� R� R~ R t rel_depth( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� � s % (
c 1 K@ s� t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � S| d d k rp | d k rp | d } n | dJ k r� | r� t | d � St | d
| �} t j j j
� r| dJ k r� | r� | n t j j j � } n | dJ k rt
j d j | � � n | } n d | k r6| r6| j d g � } n | sE| } n t j j j | � } t j j j | � } t j j j
� r�y t j j j | � Wq�t k
r�} t | | � SXn" t | | � } | r�t | | � St j j | � st | d
j | � � St j j | � sH| r0t j j | � sH| r�t j j | � r�|
dJ k r�t j j |
� r�| s�t | d j |
� � St d |
� n t j | |
� q�| r{t j j | � r�t d r�d | d d <qxt j | � d | d d <q�t d | � rAt d r"d | d d <qxt d | � d | d d <q�t d r\d | d d <q�t d | � d | d d <q�t j j | � r�t | d j | � � St j j | � r�t | d j | � � Sn t j j j
� rt d | d | d | d | d | d | � \ } } } n9 t | | | | p.g | | | | |
| | � \ } } } | rl| d j! | � n t d s�| d r�| | d <| | d <| St j j" | � s�t j j" t j j# | � � sR| r9y; t$ d | d
| d! | d" | d | d | d | d | � WqOt k
r5} t | d# j | j% � � SXqRt | d$ j | � � Sn t j j j
� r�t d% d& | d' | d( | d) | d* | d+ | � n t d% | d
| d! | d, | �d- | d | <n t j j" | � s�t | d. j | � � S| slt j j j
� rAt d/ d& | d0 | d' | d( | d) | d* | d+ | � } qlt d/ | | | | | dJ | � \ } } n g } | s~| r�t& t' | | � � } i } x- | D]" } | d1 | d2 f | | d3 <q�Wn dJ }! | r!y t( | � }! Wq!t) t* f k
r } t+ | d <d4 j | � | d <q!Xn |! rA
d5 |! k r�| sHt, | t- � r�t d6 | � }" t, |" t. j/ � r�t+ | d <d7 j | � | d <q�q�t+ | d <d8 | d <n dJ } d9 |! k r'| s�t, | t- � rt d: | � }# t, |# t. j/ � r$t+ | d <d; j | � | d <q$q-t+ | d <d< | d <n dJ } d |! k rHdJ } dJ } n d= |! k }$ d> |! k }% x�| D]�\ }& }' }( |$ rX x� |( D]� }) t j j0 |& |) � }* yx t j j j
� r�t d/ d& |* d0 | d' | d( | d) | d* | d+ | � } n( t d/ |* | | | | dJ | � \ } }+ Wq�t k
rP } | j1 j2 d? � sQ | j3 | j1 � qQ q�Xq�Wn |% rgx� |' D]� }, t j j0 |& |, � }* yx t j j j
� r� t d/ d& |* d0 | d' | d( | d) | d* | d+ | � } n( t d/ |* | | | | dJ | � \ } }+ Wqe t k
r2
} | j1 j2 d? � s3
| j3 | j1 � q3
qe Xqe WqgqgWn | r�
t4 | | | � }- t
j5 d@ |- � t6 | t& |- � |
� }. |. r�
|. | d dA <dB j | � | d <q�
n | d s�
| r�
dC j | � | d <q�
| d r�
dD j | � | d <q�
n t d r dE j | � | d <nn | d r� | d r� dJ }/ | d rI | d }/ n dF j | � | d <|/ r� dG j0 | d |/ g � | d <q� n | r� t+ | d <| d c dH 7<x* | D] }0 | d c dI j |0 � 7<q� Wn | S(K u/
Ensure that a named directory is present and has the right perms
name
The location to create or manage a directory, as an absolute path
user
The user to own the directory; this defaults to the user salt is
running as on the minion
group
The group ownership set for the directory; this defaults to the group
salt is running as on the minion. On Windows, this is ignored
recurse
Enforce user/group ownership and mode of directory recursively. Accepts
a list of strings representing what you would like to recurse. If
``mode`` is defined, will recurse on both ``file_mode`` and ``dir_mode`` if
they are defined. If ``ignore_files`` or ``ignore_dirs`` is included, files or
directories will be left unchanged respectively.
Example:
.. code-block:: yaml
/var/log/httpd:
file.directory:
- user: root
- group: root
- dir_mode: 755
- file_mode: 644
- recurse:
- user
- group
- mode
Leave files or directories unchanged:
.. code-block:: yaml
/var/log/httpd:
file.directory:
- user: root
- group: root
- dir_mode: 755
- file_mode: 644
- recurse:
- user
- group
- mode
- ignore_dirs
.. versionadded:: 2015.5.0
max_depth
Limit the recursion depth. The default is no limit=None.
'max_depth' and 'clean' are mutually exclusive.
.. versionadded:: 2016.11.0
dir_mode / mode
The permissions mode to set any directories created. Not supported on
Windows.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
file_mode
The permissions mode to set any files created if 'mode' is run in
'recurse'. This defaults to dir_mode. Not supported on Windows.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
makedirs
If the directory is located in a path without a parent directory, then
the state will fail. If makedirs is set to True, then the parent
directories will be created to facilitate the creation of the named
file.
clean
Make sure that only files that are set up by salt and required by this
function are kept. If this option is set then everything in this
directory will be deleted unless it is required.
'clean' and 'max_depth' are mutually exclusive.
require
Require other resources such as packages or files
exclude_pat
When 'clean' is set to True, exclude this pattern from removal list
and preserve in the destination.
follow_symlinks : False
If the desired path is a symlink (or ``recurse`` is defined and a
symlink is encountered while recursing), follow it and check the
permissions of the directory/file to which the symlink points.
.. versionadded:: 2014.1.4
force
If the name of the directory exists and is not a directory and
force is set to False, the state will fail. If force is set to
True, the file in the way of the directory will be deleted to
make room for the directory, unless backupname is set,
then it will be renamed.
.. versionadded:: 2014.7.0
backupname
If the name of the directory exists and is not a directory, it will be
renamed to the backupname. If the backupname already
exists and force is False, the state will fail. Otherwise, the
backupname will be removed first.
.. versionadded:: 2014.7.0
allow_symlink : True
If allow_symlink is True and the specified path is a symlink, it will be
allowed to remain if it points to a directory. If allow_symlink is False
then the state will fail, unless force is also set to True, in which case
it will be removed or renamed, depending on the value of the backupname
argument.
.. versionadded:: 2014.7.0
children_only : False
If children_only is True the base of a path is excluded when performing
a recursive operation. In case of /path/to/base, base will be ignored
while all of /path/to/base/* are still operated on.
win_owner : None
The owner of the directory. If this is not passed, user will be used. If
user is not passed, the account under which Salt is running will be
used.
.. versionadded:: 2017.7.0
win_perms : None
A dictionary containing permissions to grant and their propagation. For
example: ``{'Administrators': {'perms': 'full_control', 'applies_to':
'this_folder_only'}}`` Can be a single basic perm or a list of advanced
perms. ``perms`` must be specified. ``applies_to`` is optional and
defaults to ``this_folder_subfoler_files``.
.. versionadded:: 2017.7.0
win_deny_perms : None
A dictionary containing permissions to deny and their propagation. For
example: ``{'Administrators': {'perms': 'full_control', 'applies_to':
'this_folder_only'}}`` Can be a single basic perm or a list of advanced
perms.
.. versionadded:: 2017.7.0
win_inheritance : True
True to inherit permissions from the parent directory, False not to
inherit permission.
.. versionadded:: 2017.7.0
win_perms_reset : False
If ``True`` the existing DACL will be cleared and replaced with the
settings defined in this function. If ``False``, new entries will be
appended to the existing DACL. Default is ``False``.
.. versionadded:: 2018.3.0
Here's an example using the above ``win_*`` parameters:
.. code-block:: yaml
create_config_dir:
file.directory:
- name: 'C:\config\'
- win_owner: Administrators
- win_perms:
# Basic Permissions
dev_ops:
perms: full_control
# List of advanced permissions
appuser:
perms:
- read_attributes
- read_ea
- create_folders
- read_permissions
applies_to: this_folder_only
joe_snuffy:
perms: read
applies_to: this_folder_files
- win_deny_perms:
fred_snuffy:
perms: full_control
- win_inheritance: False
u nameu changesu resultu u commentu# Must provide name to file.directoryi����u /u' Cannot specify both max_depth and cleanR+ u� The group argument for {0} has been ignored as this is a Windows system. Please use the `win_*` parameters to set permissions in Windows.u modeu* Specified file {0} is not an absolute pathu1 File exists where the backup target {0} should gou file.removeu testu File would be forcibly replacedu forcedu File was forcibly replacedu file.is_linku" Symlink would be forcibly replacedu Symlink was forcibly replacedu$ Directory would be forcibly replacedu Directory was forcibly replacedu+ Specified location {0} exists and is a fileu. Specified location {0} exists and is a symlinkRA R� R� R� R� R� R, R� u Drive {0} is not mappedu No directory to create {0} inu
file.mkdirR R� R� R� R' RV R� u New Diru Failed to create directory {0}u file.check_permsR i i i u {0}u useru file.user_to_uidu> Failed to enforce ownership for user {0} (user does not exist)uQ user not specified, but configured as a target for recursive ownership managementu groupu file.group_to_gidu/ Failed to enforce group ownership for group {0}uR group not specified, but configured as a target for recursive ownership managementu ignore_filesu ignore_dirsu Path not foundu9 List of kept files when use file.directory with clean: %su removedu Files cleaned from directory {0}u Directory {0}/* updatedu Directory {0} updatedu Directory {0} not updatedu% Directory {0} is in the correct stateu
u)
The following errors were encountered:
u
- {0}N(7 R R R* R8 R� R5 R� R R R� R� R� t get_current_userRH R� R* R| R R� R� t get_sidR R0 R� R Rt R- R) t renameR RJ R� R� RL R{ Rc R( R+ RF R� R� R� R� R4 R� t intR R� R Rb RG R� R� RI R� (1 RA R+ R, R� R� R� R� R0 R� R� RT R� R� R/ t
allow_symlinkt
children_onlyR� R� R� R� R� Rh R R� R� R3 R4 R5 R� t errorsR� R� R� R� R. R/ R� R� R� R~ R Rm t fullR� t dir_RV R� t orig_commentt error( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyRx � s� �
!
+
$
#
%
%%
#
c 1 @ s? d �
k r �
j d � n t j j t j j j � � � � t �
d � �� t j j j
� r� � d- k r� t j
d j � � � n � � n i � d 6i d 6t d 6i d 6�
d �
k r� t �
d <d �
d <�
St g � � | f D] } | d- k ^ q� � r"t j j j
� r"t �
d
� St j j j � � � y% � j � d k � � r[d- � n Wn t k
rut � n Xt j j j � � � t � � � } | r�t �
| � St j j � � s�t �
d j � � � St | � } x- t | � D] \ } } | j d
� | | <q�Wx3 | D]+ } | j d � st �
d j | � � SqWy t d | d t � \ } } Wn1 t k
r�}! t �
d <d j |! � �
d <�
SXt j j j! | � \ � }" |" d- k r�t }" n t d d |" � }# � |# k r+t � f d � |# D� � r+t �
d <d j � |" � �
d <�
St j j" � � s�t j j# � � ret �
d j � � � St$ d s�t j j j
� r�| r�| n � } t d d � d | d | d | d | � q�t d d � d � d � d! � � q�n �
f d" � � � �
f d# � � � � � � � � � � �
� � � � f
d$ � }$ � � � � � � f d% � }% t% � | | | | | | � \ }& }' }( }) xx |( D]p \ }* }+ t& t j j' � |* � |+ d& t d' | d � d � d! | �}, |, s�q�n � t j j' � |* � |, � q�Wx |' D] }- |% |- � qWx$ |& D] \ }. }/ |$ |. |/ | � q!W� r�|) j( t) � | � � t* � t+ |) � | � }0 |0 r�t$ d r��
d r�d- �
d <n � d( |0 � q�|0 �
d d( <q�n d) j' d* � t, j- �
d � D� � j. � �
d <�
d sd+ j � � �
d <n �
d r;�
d r;d, j � � �
d <n �
S(. u�
Recurse through a subdirectory on the master and copy said subdirectory
over to the specified path.
name
The directory to set the recursion in
source
The source directory, this directory is located on the salt master file
server and is specified with the salt:// protocol. If the directory is
located on the master in the directory named spam, and is called eggs,
the source string is salt://spam/eggs
keep_source : True
Set to ``False`` to discard the cached copy of the source file once the
state completes. This can be useful for larger files to keep them from
taking up space in minion cache. However, keep in mind that discarding
the source file will result in the state needing to re-download the
source file if the state is run again.
.. versionadded:: 2017.7.3
clean
Make sure that only files that are set up by salt and required by this
function are kept. If this option is set then everything in this
directory will be deleted unless it is required.
require
Require other resources such as packages or files
user
The user to own the directory. This defaults to the user salt is
running as on the minion
group
The group ownership set for the directory. This defaults to the group
salt is running as on the minion. On Windows, this is ignored
dir_mode
The permissions mode to set on any directories created.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
.. note::
This option is **not** supported on Windows.
file_mode
The permissions mode to set on any files created.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
.. note::
This option is **not** supported on Windows.
.. versionchanged:: 2016.11.0
This option can be set to ``keep``, and Salt will keep the mode
from the Salt fileserver. This is only supported when the
``source`` URL begins with ``salt://``, or for files local to the
minion. Because the ``source`` option cannot be used with any of
the ``contents`` options, setting the ``mode`` to ``keep`` is also
incompatible with the ``contents`` options.
sym_mode
The permissions mode to set on any symlink created.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
.. note::
This option is **not** supported on Windows.
template
If this setting is applied, the named templating engine will be used to
render the downloaded file. The following templates are supported:
- :mod:`cheetah<salt.renderers.cheetah>`
- :mod:`genshi<salt.renderers.genshi>`
- :mod:`jinja<salt.renderers.jinja>`
- :mod:`mako<salt.renderers.mako>`
- :mod:`py<salt.renderers.py>`
- :mod:`wempy<salt.renderers.wempy>`
.. note::
The template option is required when recursively applying templates.
replace : True
If set to ``False`` and the file already exists, the file will not be
modified even if changes would otherwise be made. Permissions and
ownership will still be enforced, however.
context
Overrides default context variables passed to the template.
defaults
Default context passed to the template.
include_empty
Set this to True if empty directories should also be created
(default is False)
backup
Overrides the default backup mode for all replaced files. See
:ref:`backup_mode documentation <file-state-backups>` for more details.
include_pat
When copying, include only this pattern from the source. Default
is glob match; if prefixed with 'E@', then regexp match.
Example:
.. code-block:: text
- include_pat: hello* :: glob matches 'hello01', 'hello02'
... but not 'otherhello'
- include_pat: E@hello :: regexp matches 'otherhello',
'hello01' ...
exclude_pat
Exclude this pattern from the source when copying. If both
`include_pat` and `exclude_pat` are supplied, then it will apply
conditions cumulatively. i.e. first select based on include_pat, and
then within that result apply exclude_pat.
Also, when 'clean=True', exclude this pattern from the removal
list and preserve in the destination.
Example:
.. code-block:: text
- exclude_pat: APPDATA* :: glob matches APPDATA.01,
APPDATA.02,.. for exclusion
- exclude_pat: E@(APPDATA)|(TEMPDATA) :: regexp matches APPDATA
or TEMPDATA for exclusion
maxdepth
When copying, only copy paths which are of depth `maxdepth` from the
source path.
Example:
.. code-block:: text
- maxdepth: 0 :: Only include files located in the source
directory
- maxdepth: 1 :: Only include files located in the source
or immediate subdirectories
keep_symlinks
Keep symlinks when copying from the source. This option will cause
the copy operation to terminate at the symlink. If desire behavior
similar to rsync, then set this to True.
force_symlinks
Force symlink creation. This option will force the symlink creation.
If a file or directory is obstructing symlink creation it will be
recursively removed so that symlink creation can proceed. This
option is usually not needed except in special circumstances.
win_owner : None
The owner of the symlink and directories if ``makedirs`` is True. If
this is not passed, ``user`` will be used. If ``user`` is not passed,
the account under which Salt is running will be used.
.. versionadded:: 2017.7.7
win_perms : None
A dictionary containing permissions to grant
.. versionadded:: 2017.7.7
win_deny_perms : None
A dictionary containing permissions to deny
.. versionadded:: 2017.7.7
win_inheritance : None
True to inherit permissions from parent, otherwise False
.. versionadded:: 2017.7.7
u envR+ uH The group argument for {0} has been ignored as this is a Windows system.u nameu changesu resultu commentu modeuO 'mode' is not allowed in 'file.recurse'. Please use 'file_mode' and 'dir_mode'.u+ mode management is not supported on Windowsu keepu* Specified file {0} is not an absolute pathu /u salt://u, Invalid source '{0}' (must be a salt:// URI)u file.source_listu u Recurse failed: {0}u cp.list_master_dirsR[ c 3@ s( | ] } | j � d � r | Vq d S( u /N( RG ( R� R{ ( RX ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pys <genexpr>� s uJ The directory '{0}' does not exist on the salt fileserver in saltenv '{1}'u* The path {0} exists and is not a directoryu testu file.makedirs_permsR R� R� R� R' RA R, R� c @ sI � d j | g � } t | t j � r8 | j | � n
| j | � d S( Nu comment( R\ R� R R� R� t extend( R t commentR� ( R ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt add_comment s c @ s� | d t k s � d t k r1 | d � d <n | d t k r_ | d r_ � | | d � n | d r~ | d � d | <n d S( Nu resultu commentu changes( R4 R8 ( R R} ( R� R ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt merge_ret s
c @ sm � r� t j j | � r� t j j | � r� | r� i �
d 6i d 6t d 6d d 6} t d r� d j | � | d <d | d <� | | � d St d | � i d d
6| d <� | | � n i } d d g } x+ � D]# } | | k r� � | | | <q� q� Wt | d
| d � d � d � d � r&d n � d d d � d t d | d � d � d � | � } � | | � d S( Nu nameu changesu resultu u commentu testu# Replacing directory {0} with a fileu file.removeu" Replaced directory with a new fileu diffu modeu makedirsRe Rl R+ R, R� u keepRm R� R0 R> R� R Rn (
R R R� R{ R8 R R* R5 R) R� ( R Re R> R} t pass_kwargst faultsR� (
Rn R� R� R R� R, Rz Rl Rh R� RA R� R+ ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt manage_file+ s@ 0"
c @ s t j j | � d k r d S� r� t j j | � r� t j j | � r� i � d 6i d 6t d 6d d 6} t d r� d j | � | d <d | d <� | | � d St d | � i d
d 6| d <� | | � n t
| d � d
� d g d � d d d t d t d d �} � | | � d S( Nu ..u nameu changesu resultu u commentu testu Replacing {0} with a directoryu file.removeu Replaced file with a directoryu diffR+ R, R� R� R� R0 R� R� ( R R R, R� R{ R8 R R* R5 R) Rx R4 ( R R} ( R� R� R, R� RA R+ ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt manage_directoryR s. +"
R0 R� u removedu
c s@ sH | ]> \ } } d j | t | t j � r0 | n d j | � � Vq d S( u
#### {0} ####
{1}u
N( R* R� R R� R ( R� t kt v( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pys <genexpr>� s u Recursively updated {0}u) The directory {0} is in the correct stateN(/ RZ R R R* R R Ra Rb R� R� R� R5 RH R� R* R8 R4 t anyR� R R� R R[ R0 R� R
t enumerateR_ RG R) R_ R R] R^ R{ R� R Rv R6 R RL R� R� RF R RC R6 (1 RA Re Rl R� R� R+ R, R� R� t sym_modeR� R� R> R Rg Rn RU RT R: Rf t force_symlinksR� R� R� R� Rh R{ R� R t idxR� t precheckR� R� Rk t master_dirsR� R� t mng_filest mng_dirst mng_symlinksRV RQ RP R} Rc Ro Rp R� ( ( R� Rn R� R� R R� R� R, Rz Rl Rh R� RA R RX R� R+ s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� �
s� � !
.
3'
$
c @ sx t j j � � � i � d 6i g d 6g d 6g d 6d 6t d 6d d 6} � s\ t | d � St j j � � s{ t | d
� St d � � } t d d
d
� � � � f d � } � � f d � } � r� | n | } � f d � � � � } � � }
t � } t � } x� | D]� }
| |
� \ } } | r�|
| | j | j
| j | j | <| j
� d
} |
|
| j | | j � | <| j |
� q
| j |
� q
Wi d
d 6d d 6d d 6d d 6d d 6} � f d � � � � f d � � t � } x� | j � D]v \ } } d | k r"t j n t | � } d | k r]d } | � |
| | d
� O} q| � | | | | � O} qWt | | � } | j d t � i t t | � d t �d 6| d 6t t | � d t �d 6} | | d <t d r d j t | � � � | d <| rtd# | d <qtnT x+ | D]# }
t d! t j j � |
� � q'Wd" j t | � � � | d <| | d <| S($ u
Apply retention scheduling to backup storage directory.
.. versionadded:: 2016.11.0
:param name:
The filesystem path to the directory containing backups to be managed.
:param retain:
Delete the backups, except for the ones we want to keep.
The N below should be an integer but may also be the special value of ``all``,
which keeps all files matching the criteria.
All of the retain options default to None,
which means to not keep files based on this criteria.
:most_recent N:
Keep the most recent N files.
:first_of_hour N:
For the last N hours from now, keep the first file after the hour.
:first_of_day N:
For the last N days from now, keep the first file after midnight.
See also ``timezone``.
:first_of_week N:
For the last N weeks from now, keep the first file after Sunday midnight.
:first_of_month N:
For the last N months from now, keep the first file after the start of the month.
:first_of_year N:
For the last N years from now, keep the first file after the start of the year.
:param strptime_format:
A python strptime format string used to first match the filenames of backups
and then parse the filename to determine the datetime of the file.
https://docs.python.org/2/library/datetime.html#datetime.datetime.strptime
Defaults to None, which considers all files in the directory to be backups eligible for deletion
and uses ``os.path.getmtime()`` to determine the datetime.
:param timezone:
The timezone to use when determining midnight.
This is only used when datetime is pulled from ``os.path.getmtime()``.
Defaults to ``None`` which uses the timezone from the locale.
Usage example:
.. code-block:: yaml
/var/backups/example_directory:
file.retention_schedule:
- retain:
most_recent: 5
first_of_hour: 4
first_of_day: 7
first_of_week: 6 # NotImplemented yet.
first_of_month: 6
first_of_year: all
- strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2
- timezone: None
u nameu retainedu deletedu ignoredu changesu resultu u commentu, Must provide name to file.retention_scheduleu3 Name provided to file.retention must be a directoryu file.readdiri� i c @ sR y9 t j | � � } t j j j | � � } | | f SWn t k
rM d SXd S( N( NN( R t strptimeR R t dateutilst
total_secondsR� R5 ( R t tst ts_epoch( t beginning_of_unix_timet strptime_format( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt get_file_time_from_strptime� s
c @ si | d k s | d k r d St d t j j � | � � } | ra | d } t j | � � | f Sd Sd S( Nu .u ..u
file.lstatu st_mtime( NN( NN( R5 R) R R R R RC ( R RD R� ( RA t timezone( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt get_file_time_from_mtime� s
c @ s
t � � S( N( R ( ( t
dict_maker( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR�
s u
first_of_yeari u first_of_monthi u first_of_dayi u
first_of_houri u most_recentc @ sD t | t � r3 t | j � � d } � | | � St | g � Sd S( Ni ( R� Ra t sortedt keysR\ ( t fwtt
first_sub_key( t get_first( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� & s c @ s� | d k r � | � St � } x^ t | j � d t �D]D } | t | � } | d k r^ Pn | � | | | d | � O} q8 W| Sd S( Ni t reversei ( R\ R� R� R8 R� ( R� t deptht nt
result_setR� t needed( R� t get_first_n_at_depth( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� - s
"u allu
first_of_weekR� u testu. {0} backups would have been removed from {1}.
u file.removeu# {0} backups were removed from {1}.
N( R R R* R8 R� R{ R) R R\ t yeart montht dayt hourt isocalendart weekdayRK t itemst syst maxsizeR� RF t sortR� R R* R� R5 R ( RA t retainR� R� R t all_filesR� R� t
get_file_timet files_by_ymdt files_by_y_week_dowt relevant_filest
ignored_filesR R� R� t week_of_yeart RETAIN_TO_DEPTHt retained_filest retention_rulet
keep_countt first_of_week_deptht deletable_filesR� ( ( R� R� R� R� RA R� R� s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt retention_schedule� s| @
&
!
!
c C@ s� t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � St | d | d | d |
d
| d t �t | � \ } } | s� t | | � S| r� | j � p� | } | d k r� t | d � Sd
g } | | k r� | d k r� t | d j
| � � S~ t d | | d | d
| d | d | d | d | d | d | d |
� } | r�| | d d <t d r}d | d <d | d <q�t | d <d | d <n t | d <d | d <| S( u
Line-based editing of a file.
.. versionadded:: 2015.8.0
:param name:
Filesystem path to the file to be edited.
:param content:
Content of the line. Allowed to be empty if mode=delete.
:param match:
Match the target line for an action by
a fragment of a string or regular expression.
If neither ``before`` nor ``after`` are provided, and ``match``
is also ``None``, match becomes the ``content`` value.
:param mode:
Defines how to edit a line. One of the following options is
required:
- ensure
If line does not exist, it will be added.
- replace
If line already exists, it will be replaced.
- delete
Delete the line, once found.
- insert
Insert a line.
.. note::
If ``mode=insert`` is used, at least one of the following
options must also be defined: ``location``, ``before``, or
``after``. If ``location`` is used, it takes precedence
over the other two options.
:param location:
Defines where to place content in the line. Note this option is only
used when ``mode=insert`` is specified. If a location is passed in, it
takes precedence over both the ``before`` and ``after`` kwargs. Valid
locations are:
- start
Place the content at the beginning of the file.
- end
Place the content at the end of the file.
:param before:
Regular expression or an exact case-sensitive fragment of the string.
This option is only used when either the ``ensure`` or ``insert`` mode
is defined.
:param after:
Regular expression or an exact case-sensitive fragment of the string.
This option is only used when either the ``ensure`` or ``insert`` mode
is defined.
:param show_changes:
Output a unified diff of the old file and the new file.
If ``False`` return a boolean if any changes were made.
Default is ``True``
.. note::
Using this option will store two copies of the file in-memory
(the original version and the edited version) in order to generate the diff.
:param backup:
Create a backup of the original file with the extension:
"Year-Month-Day-Hour-Minutes-Seconds".
:param quiet:
Do not raise any exceptions. E.g. ignore the fact that the file that is
tried to be edited does not exist and nothing really happened.
:param indent:
Keep indentation with the previous line. This option is not considered when
the ``delete`` mode is specified.
:param create:
Create an empty file if doesn't exists.
.. versionadded:: 2016.11.0
:param user:
The user to own the file, this defaults to the user salt is running as
on the minion.
.. versionadded:: 2016.11.0
:param group:
The group ownership set for the file, this defaults to the group salt
is running as on the minion On Windows, this is ignored.
.. versionadded:: 2016.11.0
:param file_mode:
The permissions to set on this file, aka 644, 0775, 4664. Not supported
on Windows.
.. versionadded:: 2016.11.0
If an equal sign (``=``) appears in an argument to a Salt command, it is
interpreted as a keyword argument in the format of ``key=val``. That
processing can be bypassed in order to pass an equal sign through to the
remote shell command by manually specifying the kwarg:
.. code-block:: yaml
update_config:
file.line:
- name: /etc/myconfig.conf
- mode: ensure
- content: my key = my value
- before: somekey.*?
u nameu changesu resultu u commentu Must provide name to file.lineRd R+ R, R� R> u. Mode was not defined. How to process the file?u deleteu( Content can only be empty if mode is {0}u file.lineR8 t locationt beforet afterRo Rn t quiett indentu diffu testu Changes would be madeu Changes were madeu No changes needed to be madeN(
R R R* R8 R� R� R4 R� R R5 R* R) R ( RA t contentR8 R� R� R� R� Ro Rn R� R� Rd R+ R, R� R t check_rest check_msgt modeswithemptycontentR� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� c sL z
i i u .bakc
C@ sO t j j | � } i | d 6i d 6t d 6d d 6}
| sG t |
d � St | � \ } } | s� | r d | k r d |
d <|
St |
| � Sn t d | | | d
| d | d | d
| d | d | d | d t d d |
d | d | � } | r7| |
d d <t d r d |
d <d |
d <qKt |
d <d |
d <n t |
d <d |
d <|
S( ua
Maintain an edit in a file.
.. versionadded:: 0.17.0
name
Filesystem path to the file to be edited. If a symlink is specified, it
will be resolved to its target.
pattern
A regular expression, to be matched using Python's
:py:func:`re.search`.
.. note::
If you need to match a literal string that contains regex special
characters, you may want to use salt's custom Jinja filter,
``regex_escape``.
.. code-block:: jinja
{{ 'http://example.com?foo=bar%20baz' | regex_escape }}
repl
The replacement text
count
Maximum number of pattern occurrences to be replaced. Defaults to 0.
If count is a positive integer n, no more than n occurrences will be
replaced, otherwise all occurrences will be replaced.
flags
A list of flags defined in the ``re`` module documentation from the
Python standard library. Each list item should be a string that will
correlate to the human-friendly flag name. E.g., ``['IGNORECASE',
'MULTILINE']``. Optionally, ``flags`` may be an int, with a value
corresponding to the XOR (``|``) of all the desired flags. Defaults to
``8`` (which equates to ``['MULTILINE']``).
.. note::
``file.replace`` reads the entire file as a string to support
multiline regex patterns. Therefore, when using anchors such as
``^`` or ``$`` in the pattern, those anchors may be relative to
the line OR relative to the file. The default for ``file.replace``
is to treat anchors as relative to the line, which is implemented
by setting the default value of ``flags`` to ``['MULTILINE']``.
When overriding the default value for ``flags``, if
``'MULTILINE'`` is not present then anchors will be relative to
the file. If the desired behavior is for anchors to be relative to
the line, then simply add ``'MULTILINE'`` to the list of flags.
bufsize
How much of the file to buffer into memory at once. The default value
``1`` processes one line at a time. The special value ``file`` may be
specified which will read the entire file into memory before
processing.
append_if_not_found : False
If set to ``True``, and pattern is not found, then the content will be
appended to the file.
.. versionadded:: 2014.7.0
prepend_if_not_found : False
If set to ``True`` and pattern is not found, then the content will be
prepended to the file.
.. versionadded:: 2014.7.0
not_found_content
Content to use for append/prepend if not found. If ``None`` (default),
uses ``repl``. Useful when ``repl`` uses references to group in
pattern.
.. versionadded:: 2014.7.0
backup
The file extension to use for a backup of the file before editing. Set
to ``False`` to skip making a backup.
show_changes : True
Output a unified diff of the old file and the new file. If ``False``
return a boolean if any changes were made. Returns a boolean or a
string.
.. note:
Using this option will store two copies of the file in memory (the
original version and the edited version) in order to generate the
diff. This may not normally be a concern, but could impact
performance if used with large files.
ignore_if_missing : False
.. versionadded:: 2016.3.4
Controls what to do if the file is missing. If set to ``False``, the
state will display an error raised by the execution module. If set to
``True``, the state will simply report no changes.
backslash_literal : False
.. versionadded:: 2016.11.7
Interpret backslashes as literal backslashes for the repl and not
escape characters. This will help when using append/prepend so that
the backslashes are not interpreted for the repl on the second run of
the state.
For complex regex patterns, it can be useful to avoid the need for complex
quoting and escape sequences by making use of YAML's multiline string
syntax.
.. code-block:: yaml
complex_search_and_replace:
file.replace:
# <...snip...>
- pattern: |
CentOS \(2.6.32[^\\n]+\\n\s+root[^\\n]+\\n\)+
.. note::
When using YAML multiline string syntax in ``pattern:``, make sure to
also use that syntax in the ``repl:`` part, or you might loose line
feeds.
u nameu changesu resultu u commentu! Must provide name to file.replaceu file not foundu No changes needed to be madeu file.replaceR7 R� t bufsizet append_if_not_foundt prepend_if_not_foundt not_found_contentRn t dry_runu testRo t ignore_if_missingt backslash_literalu diffu Changes would have been madeu Changes were madeN( R R R* R8 R� R� R) R R5 ( RA t patternt replR7 R� R� R� R� R� Rn Ro R� R� R R� R� R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR> sJ �
u #-- start managed zone --u #-- end managed zone --c % C@ s t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � S| d! k r\ g } n | d! k rq g } n t d | d | d | d
| � \ } } } | s� t | | � St | � \ } } | s� t | | � St � \ } } | | k r�| | } | j | g � } g | D], } t
d | | k r| | k r| ^ q} | seg | D] } | ^ qP} n xO | D]D } | | } x1 | D]) } |
d k r�| }
q�|
d | 7}
q�WqlWn | r)t d
| d | d | d | � } | d s�| S| d } x0 t | � D] \ }! }" |
t
j |" � 7}
qWn yH t d | | | d |
d | d | d |
d t d d | d | �}# Wn4 t k
r�}$ t j d � d j |$ � | d <| SX|# r�|# | d d <t d r�d! | d <d | d <qt | d <d | d <n t | d <d | d <| S(" u
Maintain an edit in a file in a zone delimited by two line markers
.. versionadded:: 2014.1.0
.. versionchanged:: 2017.7.5,2018.3.1
``append_newline`` argument added. Additionally, to improve
idempotence, if the string represented by ``marker_end`` is found in
the middle of the line, the content preceding the marker will be
removed when the block is replaced. This allows one to remove
``append_newline: False`` from the SLS and have the block properly
replaced if the end of the content block is immediately followed by the
``marker_end`` (i.e. no newline before the marker).
A block of content delimited by comments can help you manage several lines
entries without worrying about old entries removal. This can help you
maintaining an un-managed file containing manual edits.
.. note::
This function will store two copies of the file in-memory (the original
version and the edited version) in order to detect changes and only
edit the targeted file if necessary.
Additionally, you can use :py:func:`file.accumulated
<salt.states.file.accumulated>` and target this state. All accumulated
data dictionaries' content will be added in the content block.
name
Filesystem path to the file to be edited
marker_start
The line content identifying a line as the start of the content block.
Note that the whole line containing this marker will be considered, so
whitespace or extra content before or after the marker is included in
final output
marker_end
The line content identifying the end of the content block. As of
versions 2017.7.5 and 2018.3.1, everything up to the text matching the
marker will be replaced, so it's important to ensure that your marker
includes the beginning of the text you wish to replace.
content
The content to be used between the two lines identified by
``marker_start`` and ``marker_end``
source
The source file to download to the minion, this source file can be
hosted on either the salt master server, or on an HTTP or FTP server.
Both HTTPS and HTTP are supported as well as downloading directly
from Amazon S3 compatible URLs with both pre-configured and automatic
IAM credentials. (see s3.get state documentation)
File retrieval from Openstack Swift object storage is supported via
swift://container/object_path URLs, see swift.get documentation.
For files hosted on the salt file server, if the file is located on
the master in the directory named spam, and is called eggs, the source
string is salt://spam/eggs. If source is left blank or None
(use ~ in YAML), the file will be created as an empty file and
the content will not be managed. This is also the case when a file
already exists and the source is undefined; the contents of the file
will not be changed or managed.
If the file is hosted on a HTTP or FTP server then the source_hash
argument is also required.
A list of sources can also be passed in to provide a default source and
a set of fallbacks. The first source in the list that is found to exist
will be used and subsequent entries in the list will be ignored.
.. code-block:: yaml
file_override_example:
file.blockreplace:
- name: /etc/example.conf
- source:
- salt://file_that_does_not_exist
- salt://file_that_exists
source_hash
This can be one of the following:
1. a source hash string
2. the URI of a file that contains source hash strings
The function accepts the first encountered long unbroken alphanumeric
string of correct length as a valid hash, in order from most secure to
least secure:
.. code-block:: text
Type Length
====== ======
sha512 128
sha384 96
sha256 64
sha224 56
sha1 40
md5 32
See the ``source_hash`` parameter description for :mod:`file.managed
<salt.states.file.managed>` function for more details and examples.
template : jinja
Templating engine to be used to render the downloaded file. The
following engines are supported:
- :mod:`cheetah <salt.renderers.cheetah>`
- :mod:`genshi <salt.renderers.genshi>`
- :mod:`jinja <salt.renderers.jinja>`
- :mod:`mako <salt.renderers.mako>`
- :mod:`py <salt.renderers.py>`
- :mod:`wempy <salt.renderers.wempy>`
context
Overrides default context variables passed to the template
defaults
Default context passed to the template
append_if_not_found : False
If markers are not found and this option is set to ``True``, the
content block will be appended to the file.
prepend_if_not_found : False
If markers are not found and this option is set to ``True``, the
content block will be prepended to the file.
backup
The file extension to use for a backup of the file if any edit is made.
Set this to ``False`` to skip making a backup.
dry_run : False
If ``True``, do not make any edits to the file and simply return the
changes that *would* be made.
show_changes : True
Controls how changes are presented. If ``True``, the ``Changes``
section of the state return will contain a unified diff of the changes
made. If False, then it will contain a boolean (``True`` if any changes
were made, otherwise ``False``).
append_newline
Controls whether or not a newline is appended to the content block. If
the value of this argument is ``True`` then a newline will be added to
the content block. If it is ``False``, then a newline will *not* be
added to the content block. If it is unspecified, then a newline will
only be added to the content block if it does not already end in a
newline.
.. versionadded:: 2017.7.5,2018.3.1
Example of usage with an accumulator and with a variable:
.. code-block:: jinja
{% set myvar = 42 %}
hosts-config-block-{{ myvar }}:
file.blockreplace:
- name: /etc/hosts
- marker_start: "# START managed zone {{ myvar }} -DO-NOT-EDIT-"
- marker_end: "# END managed zone {{ myvar }} --"
- content: 'First line of content'
- append_if_not_found: True
- backup: '.bak'
- show_changes: True
hosts-config-block-{{ myvar }}-accumulated1:
file.accumulated:
- filename: /etc/hosts
- name: my-accumulator-{{ myvar }}
- text: "text 2"
- require_in:
- file: hosts-config-block-{{ myvar }}
hosts-config-block-{{ myvar }}-accumulated2:
file.accumulated:
- filename: /etc/hosts
- name: my-accumulator-{{ myvar }}
- text: |
text 3
text 4
- require_in:
- file: hosts-config-block-{{ myvar }}
will generate and maintain a block of content in ``/etc/hosts``:
.. code-block:: text
# START managed zone 42 -DO-NOT-EDIT-
First line of content
text 2
text 3
text 4
# END managed zone 42 --
u nameu changesu resultu u commentu& Must provide name to file.blockreplaceRe R� R� R� u __id__u
R R� R R� u datau file.blockreplaceR� R� R� Rn R� u testRo t append_newlineu Encountered error managing blocku? Encountered error managing block: {0}. See the log for details.u diffu Changes would be madeu Changes were madeu No changes needed to be madeN( R R R* R4 R� R5 R� R� R# R| t __low__R R� R R� R) R R. RH t exceptionR* R8 (% RA t marker_startt
marker_endRe R� R� R� R� R R� R� R� R� Rn Ro R� R t ok_R- t sl_R� R� R� t
accum_depst accumulatort depst at filteredt acct acc_contentR� t tmprett textt indexR R� R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt blockreplace� s� �
,
u #c
C@ s� t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � St | � \ } } | sl t | | � St j d d | � } | | } t d | | d
t �r� t } n t } | s� t d | | d
t � r t d | | d
t �rd | d <t | d <| St | d j
| � � Sn t d
rVd | d | <d j
| � | d <d | d <| St
j j j | d � �= }
|
j � } t j r�| j t � } n | j t � } Wd QXt d | | | t | � t
j j j | d � �= }
|
j � } t j r | j t � } n | j t � } Wd QXt d | | d
t �| d <| | k r�t d | � shd | d d <q�d j t j | | � � | d d <n | d r�d | d <n
d | d <| S( u�
Comment out specified lines in a file.
name
The full path to the file to be edited
regex
A regular expression used to find the lines that are to be commented;
this pattern will be wrapped in parenthesis and will move any
preceding/trailing ``^`` or ``$`` characters outside the parenthesis
(e.g., the pattern ``^foo$`` will be rewritten as ``^(foo)$``)
Note that you _need_ the leading ^, otherwise each time you run
highstate, another comment char will be inserted.
char : ``#``
The character to be inserted at the beginning of a line in order to
comment it out
backup : ``.bak``
The file will be backed up before edit with this file extension
.. warning::
This backup will be overwritten each time ``sed`` / ``comment`` /
``uncomment`` is called. Meaning the backup will only be useful
after the first invocation.
Set to False/None to not keep a backup.
Usage:
.. code-block:: yaml
/etc/fstab:
file.comment:
- regex: ^bind 127.0.0.1
.. versionadded:: 0.9.5
u nameu changesu resultu u commentu! Must provide name to file.commentu ^(\(\?[iLmsux]\))?\^?(.*?)\$?$u \2u file.searcht multilineu Pattern already commentedu {0}: Pattern not foundu testu updatedu File {0} is set to be updatedu rbNu file.comment_lineu
files.is_textu Replace binary fileu diffu Commented lines successfullyu" Expected commented lines not found( R R R* R4 R� R� R? t subR) R8 R* R R5 R R R R R� R t PY3Rb t __salt_system_encoding__R t __utils__R t difflibt unified_diff(
RA RN t charRn R R� R� t unanchor_regext
comment_regext commentedR t slinest nlines( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� � s\ %
&
c
C@ sh t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � St | � \ } } | sl t | | � St d | d j | j d � � d
t �r� d | d <t | d <| St d | d j | | j d � � d
t �r� n t | d
j | � � St
d r/d | d | <d j | � | d <d | d <| St j
j j | d � �" } t j
j j | j � � } Wd QXt d | | | t | � t j
j j | d � �" } t j
j j | j � � } Wd QXt d | d j | j d � � d
t �| d <| | k rCt d | � s d | d d <qCd j t j | | � � | d d <n | d rZd | d <n
d | d <| S( u]
Uncomment specified commented lines in a file
name
The full path to the file to be edited
regex
A regular expression used to find the lines that are to be uncommented.
This regex should not include the comment character. A leading ``^``
character will be stripped for convenience (for easily switching
between comment() and uncomment()). The regex will be searched for
from the beginning of the line, ignoring leading spaces (we prepend
'^[ \t]*')
char : ``#``
The character to remove in order to uncomment a line
backup : ``.bak``
The file will be backed up before edit with this file extension;
.. warning::
This backup will be overwritten each time ``sed`` / ``comment`` /
``uncomment`` is called. Meaning the backup will only be useful
after the first invocation.
Set to False/None to not keep a backup.
Usage:
.. code-block:: yaml
/etc/adduser.conf:
file.uncomment:
- regex: EXTRA_GROUPS
.. versionadded:: 0.9.5
u nameu changesu resultu u commentu# Must provide name to file.uncommentu file.searchu ^[ ]*{0}u ^R u Pattern already uncommentedu {0}[ ]*{1}u {0}: Pattern not foundu testu updatedu File {0} is set to be updatedu rbNu file.comment_lineu
files.is_textu Replace binary fileu diffu Uncommented lines successfullyu$ Expected uncommented lines not found( R R R* R4 R� R� R) R* R� R8 R R5 R R R R Ra Rb t readlinesR
R R R (
RA RN R
Rn R R� R� R R R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt uncommentb sZ $
!!
&
c C@ s i | d 6i d 6t d 6d d 6} | s5 t | d � St j j | � } | d k r\ g } n | d k rq g } n t d | d | d | d
| � \ } }
} | s� t | |
� S| t k r�t j j | � } t d r� d j
| � | d <d | d <q�t d
| � s�y t d | � Wn) t
k
rB} t | d j
| j � � SXt j j j � rat | � n t | � \ } } } | s�| | d <t | | � Sq�n t | � \ } } | s�t | d | �} t d r�| St | � \ } } | s�t | | � Sn | r;t d | d | d | d | � } | d s.| S| d } n t | � } t j j j | d � �: } | j � } t j r�| j t � } n | j � } Wd QXg } y� x� | D]� } |
r�t d | t j j! j" | � d t �rq�qn t d | | d t �rq�n x* | j � D] } | j# d j
| � � qWq�WWn t$ k
rVt | d � SXt d r d j
| � | d <d | d <t% | � } | j& | � | | k r�t' d | � s�d | d d <qd j( t) j* | | � � | d d <n d! j
| � | d <t | d <| S| rAt d" | d# | �d$ j
t+ | � � | d <n d! j
| � | d <t j j j | d � �: } | j � } t j r�| j t � } n | j � } Wd QX| | k r�t' d | � s�d | d d <q�d j( t) j* | | � � | d d <n t | d <| S(% u�
Ensure that some text appears at the end of a file.
The text will not be appended if it already exists in the file.
A single string of text or a list of strings may be appended.
name
The location of the file to append to.
text
The text to be appended, which can be a single string or a list
of strings.
makedirs
If the file is located in a path without a parent directory,
then the state will fail. If makedirs is set to True, then
the parent directories will be created to facilitate the
creation of the named file. Defaults to False.
source
A single source file to append. This source file can be hosted on either
the salt master server, or on an HTTP or FTP server. Both HTTPS and
HTTP are supported as well as downloading directly from Amazon S3
compatible URLs with both pre-configured and automatic IAM credentials
(see s3.get state documentation). File retrieval from Openstack Swift
object storage is supported via swift://container/object_path URLs
(see swift.get documentation).
For files hosted on the salt file server, if the file is located on
the master in the directory named spam, and is called eggs, the source
string is salt://spam/eggs.
If the file is hosted on an HTTP or FTP server, the source_hash argument
is also required.
source_hash
This can be one of the following:
1. a source hash string
2. the URI of a file that contains source hash strings
The function accepts the first encountered long unbroken alphanumeric
string of correct length as a valid hash, in order from most secure to
least secure:
.. code-block:: text
Type Length
====== ======
sha512 128
sha384 96
sha256 64
sha224 56
sha1 40
md5 32
See the ``source_hash`` parameter description for :mod:`file.managed
<salt.states.file.managed>` function for more details and examples.
template
The named templating engine will be used to render the appended-to file.
Defaults to ``jinja``. The following templates are supported:
- :mod:`cheetah<salt.renderers.cheetah>`
- :mod:`genshi<salt.renderers.genshi>`
- :mod:`jinja<salt.renderers.jinja>`
- :mod:`mako<salt.renderers.mako>`
- :mod:`py<salt.renderers.py>`
- :mod:`wempy<salt.renderers.wempy>`
sources
A list of source files to append. If the files are hosted on an HTTP or
FTP server, the source_hashes argument is also required.
source_hashes
A list of source_hashes corresponding to the sources list specified in
the sources argument.
defaults
Default context passed to the template.
context
Overrides default context variables passed to the template.
ignore_whitespace
.. versionadded:: 2015.8.4
Spaces and Tabs in text are ignored by default, when searching for the
appending content, one space or multiple tabs are the same for salt.
Set this option to ``False`` if you want to change this behavior.
Multi-line example:
.. code-block:: yaml
/etc/motd:
file.append:
- text: |
Thou hadst better eat salt with the Philosophers of Greece,
than sugar with the Courtiers of Italy.
- Benjamin Franklin
Multiple lines of text:
.. code-block:: yaml
/etc/motd:
file.append:
- text:
- Trust no one unless you have eaten much salt with him.
- "Salt is born of the purest of parents: the sun and the sea."
Gather text from multiple template files:
.. code-block:: yaml
/etc/motd:
file:
- append
- template: jinja
- sources:
- salt://motd/devops-messages.tmpl
- salt://motd/hr-messages.tmpl
- salt://motd/general-messages.tmpl
.. versionadded:: 0.9.5
u nameu changesu resultu u commentu Must provide name to file.appendRe R� R� R� u testu" Directory {0} is set to be updatedu file.directory_existsRA u Drive {0} is not mappedR0 R R� R R� u datau rbNu file.searchR u {0}u) No text found to append. Nothing appendedu File {0} is set to be updatedu
files.is_textu Replace binary fileu diffu
u File {0} is in correct stateu file.appendt argsu Appended {0} lines(, R4 R� R R R* R5 R� R8 Rc R R* R) R( R R+ R R R� R� R� R� R� t touchR R
R R R� R R Rb R R RD t build_whitespace_split_regexR� R� RF R� R
R R R R� ( RA R R0 Re R� R� R� R� R R� t ignore_whitespaceR R� R- R� Rc R� R� R� t
check_changest touch_rett retry_rest retry_msgR R R t append_linest chunkt line_itemR ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� � s� �
"
&
&
c $ C@ s� t j j | � } i | d 6i d 6t d 6d d 6} | sG t | d � S| d k r\ g } n | d k rq g } n t d | d | d | d
| � \ } }
} | s� t | |
� S| t k rot j j | � } t d | � soy t
d | � Wn) t k
r} t | d
j | j
� � SXt j j j � r7t | � n t | � \ } } } | sl| | d <t | | � Sqon t | � \ } } | s�t | d | �} t d r�| St | � \ } } | s�t | | � Sn | rt d | d | d | d | � } | d s| S| d } n t | � } t j j j | d � �= } | j � } t j r_| j t � } n | j t � } Wd QXd } g } g } x� | D]� } |
s�t d | t j j! j" | � d t �r�q�q�n | j � } xe | D]] } t d r#d j | � | d <d | d <| j# d j | � � n
| j# | � | d 7} q�Wq�Wt d r�| | } | | k r�t$ d | � s�d | d d <n# d j% t& j' | | � � | d d <d | d <n d j | � | d <t | d <| S|
r�t j j j | d � �� } | j � }! t j r |! j t � }! n |! j t � }! |! d t( | � !}" g }# x |" D] } |# | j � 7}# qKW|# | k r�t d! | | � n d } Wd QXn t d! | | � t j j j | d � �= } | j � } t j r�| j t � } n | j t � } Wd QX| | k rOt$ d | � s)d | d d <qOd j% t& j' | | � � | d d <n | rkd" j | � | d <n d j | � | d <t | d <| S(# u�
Ensure that some text appears at the beginning of a file
The text will not be prepended again if it already exists in the file. You
may specify a single line of text or a list of lines to append.
name
The location of the file to append to.
text
The text to be appended, which can be a single string or a list
of strings.
makedirs
If the file is located in a path without a parent directory,
then the state will fail. If makedirs is set to True, then
the parent directories will be created to facilitate the
creation of the named file. Defaults to False.
source
A single source file to append. This source file can be hosted on either
the salt master server, or on an HTTP or FTP server. Both HTTPS and
HTTP are supported as well as downloading directly from Amazon S3
compatible URLs with both pre-configured and automatic IAM credentials
(see s3.get state documentation). File retrieval from Openstack Swift
object storage is supported via swift://container/object_path URLs
(see swift.get documentation).
For files hosted on the salt file server, if the file is located on
the master in the directory named spam, and is called eggs, the source
string is salt://spam/eggs.
If the file is hosted on an HTTP or FTP server, the source_hash argument
is also required.
source_hash
This can be one of the following:
1. a source hash string
2. the URI of a file that contains source hash strings
The function accepts the first encountered long unbroken alphanumeric
string of correct length as a valid hash, in order from most secure to
least secure:
.. code-block:: text
Type Length
====== ======
sha512 128
sha384 96
sha256 64
sha224 56
sha1 40
md5 32
See the ``source_hash`` parameter description for :mod:`file.managed
<salt.states.file.managed>` function for more details and examples.
template
The named templating engine will be used to render the appended-to file.
Defaults to ``jinja``. The following templates are supported:
- :mod:`cheetah<salt.renderers.cheetah>`
- :mod:`genshi<salt.renderers.genshi>`
- :mod:`jinja<salt.renderers.jinja>`
- :mod:`mako<salt.renderers.mako>`
- :mod:`py<salt.renderers.py>`
- :mod:`wempy<salt.renderers.wempy>`
sources
A list of source files to append. If the files are hosted on an HTTP or
FTP server, the source_hashes argument is also required.
source_hashes
A list of source_hashes corresponding to the sources list specified in
the sources argument.
defaults
Default context passed to the template.
context
Overrides default context variables passed to the template.
ignore_whitespace
.. versionadded:: 2015.8.4
Spaces and Tabs in text are ignored by default, when searching for the
appending content, one space or multiple tabs are the same for salt.
Set this option to ``False`` if you want to change this behavior.
Multi-line example:
.. code-block:: yaml
/etc/motd:
file.prepend:
- text: |
Thou hadst better eat salt with the Philosophers of Greece,
than sugar with the Courtiers of Italy.
- Benjamin Franklin
Multiple lines of text:
.. code-block:: yaml
/etc/motd:
file.prepend:
- text:
- Trust no one unless you have eaten much salt with him.
- "Salt is born of the purest of parents: the sun and the sea."
Optionally, require the text to appear exactly as specified
(order and position). Combine with multi-line or multiple lines of input.
.. code-block:: yaml
/etc/motd:
file.prepend:
- header: True
- text:
- This will be the very first line in the file.
- The 2nd line, regardless of duplicates elsewhere in the file.
- These will be written anew if they do not appear verbatim.
Gather text from multiple template files:
.. code-block:: yaml
/etc/motd:
file:
- prepend
- template: jinja
- sources:
- salt://motd/devops-messages.tmpl
- salt://motd/hr-messages.tmpl
- salt://motd/general-messages.tmpl
.. versionadded:: 2014.7.0
u nameu changesu resultu u commentu! Must provide name to file.prependRe R� R� R� u file.directory_existsRA u Drive {0} is not mappedR0 u testR R� R R� u datau rbNi u file.searchR u File {0} is set to be updatedu {0}
i u
files.is_textu Replace binary fileu diffu File {0} is in correct stateu file.prependu Prepended {0} lines() R R R* R4 R� R5 R� R8 Rc R) R( R R* R+ R R R� R� R� R� R� R R R R
R R R� R R Rb R R RD R R� R
R R R R� ($ RA R R0 Re R� R� R� R� R R� t headerR R� R- R� Rc R� R� R� R R R R R R R R7 t
test_linest prefaceR t linesR� R Rp t target_headt target_lines( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt prepend� s� �
#
&
c ) @ s� i � d 6i d 6t d 6d d 6}
t j j j d � sE d |
d <|
St } � s_ d |
d <|
Sy t j j � � � Wn% t k
r� d j � � |
d <|
SXt j j � � s� d
j � � |
d <|
St j j
� � s� d j � � |
d <|
St j j � � } x? dG D]7 } | | k r|
j d g � j
d j | � � qqW| d3 k r�y t j j | � } Wn% t k
r�d j | � |
d <|
SXt j j | � s�d j | � |
d <|
St j j | � s�d j | � |
d <|
Sn g � t j j j | � } d } t | � d } g } x�| | k r�| | } t | t j � sVt j | � } n x- dH D] } | j | � r]| } Pq]q]Wd3 } | d3 k r�| j
| � n | j d � r�y t | d � }
Wq�t k
r�d |
d <|
SXn� | j d � r�d | k rDy t | j d d � d � }
Wq�t k
r@d! |
d <|
SXq�y t | | d � }
Wn t k
rzd! |
d <|
SX| d 7} n
� j
| � | d 7} q W| r�d" j d# j | � � |
d <|
S� } y t d$ | | t � d } Wn+ t k
r} t |
d <| j |
d <|
SX| d3 k r�t j j j | � \ } } | j d% � r�| d3 k r�| | k r�|
j d g � j
d& � q�| d' j | � 7} q�n g } zvt j j! j" � } | j
| � z� yi t# d( } t t# d( <t t$ j% t d) j& j# d( <t' | d* | d+ | d, | d- | d. | d/ | d0 | �} WnL t k
r�} d1 j t j j j( | � | � } t) j* | � | |
d <|
SXt) j+ d2 | � Wd3 | t# d( <| t$ j% t d) j& j# d( <X| d s�t) j+ d4 t j j j( | � � | Sd3 t � � f d5 � } | d3 k r| }! n t j j! j" � }! | j
|! � t j j! j" � }" | j
|" � d d |! d |" g }# | r�|
d3 k r�|# j
d6 j |
� � n | | |# � }$ |$ d7 d k rp| |! d8 d9 g d: t, �}% |% d7 d k }& |& r�d; |
d <t, |
d <|
Sd< |
d <| d3 k r$|
d c d= 7<n t- j- t# � }' t |' d> <|
d c d? t j. j/ |$ d@ |' dA dB �7<|
Sn t# d( r�d3 |
d <dC |
d <|$ |
d <|
Sg }# | r�|
d3 k r�|# j
d6 j |
� � n | | |# � |
d <|
d d7 d k r dD |
d <t, |
d <n
dE |
d <|
SWd3 x` | D]X }( y t j0 |( � Wq$t1 k
r{} | j2 t j2 j3 k r|t) j4 dF |( | � q|q$Xq$WXd3 S(I u
Ensure that a patch has been applied to the specified file or directory
.. versionchanged:: 2019.2.0
The ``hash`` and ``dry_run_first`` options are now ignored, as the
logic which determines whether or not the patch has already been
applied no longer requires them. Additionally, this state now supports
patch files that modify more than one file. To use these sort of
patches, specify a directory (and, if necessary, the ``strip`` option)
instead of a file.
.. note::
A suitable ``patch`` executable must be available on the minion. Also,
keep in mind that the pre-check this state does to determine whether or
not changes need to be made will create a temp file and send all patch
output to that file. This means that, in the event that the patch would
not have applied cleanly, the comment included in the state results will
reference a temp file that will no longer exist once the state finishes
running.
name
The file or directory to which the patch should be applied
source
The patch file to apply
.. versionchanged:: 2019.2.0
The source can now be from any file source supported by Salt
(``salt://``, ``http://``, ``https://``, ``ftp://``, etc.).
Templating is also now supported.
source_hash
Works the same way as in :py:func:`file.managed
<salt.states.file.managed>`.
.. versionadded:: 2019.2.0
source_hash_name
Works the same way as in :py:func:`file.managed
<salt.states.file.managed>`
.. versionadded:: 2019.2.0
skip_verify
Works the same way as in :py:func:`file.managed
<salt.states.file.managed>`
.. versionadded:: 2019.2.0
template
Works the same way as in :py:func:`file.managed
<salt.states.file.managed>`
.. versionadded:: 2019.2.0
context
Works the same way as in :py:func:`file.managed
<salt.states.file.managed>`
.. versionadded:: 2019.2.0
defaults
Works the same way as in :py:func:`file.managed
<salt.states.file.managed>`
.. versionadded:: 2019.2.0
options
Extra options to pass to patch. This should not be necessary in most
cases.
.. note::
For best results, short opts should be separate from one another.
The ``-N`` and ``-r``, and ``-o`` options are used internally by
this state and cannot be used here. Additionally, instead of using
``-pN`` or ``--strip=N``, use the ``strip`` option documented
below.
reject_file
If specified, any rejected hunks will be written to this file. If not
specified, then they will be written to a temp file which will be
deleted when the state finishes running.
.. important::
The parent directory must exist. Also, this will overwrite the file
if it is already present.
.. versionadded:: 2019.2.0
strip
Number of directories to strip from paths in the patch file. For
example, using the below SLS would instruct Salt to use ``-p1`` when
applying the patch:
.. code-block:: yaml
/etc/myfile.conf:
file.patch:
- source: salt://myfile.patch
- strip: 1
.. versionadded:: 2019.2.0
In previous versions, ``-p1`` would need to be passed as part of
the ``options`` value.
saltenv
Specify the environment from which to retrieve the patch file indicated
by the ``source`` parameter. If not provided, this defaults to the
environment from which the state is being executed.
.. note::
Ignored when the patch file is from a non-``salt://`` source.
**Usage:**
.. code-block:: yaml
# Equivalent to ``patch --forward /opt/myfile.txt myfile.patch``
/opt/myfile.txt:
file.patch:
- source: salt://myfile.patch
u nameu changesu resultu u commentu patchu$ patch executable not found on minionu* A file/directory to be patched is requiredu Invalid path '{0}'u {0} is not an absolute pathu {0} does not existu hashu
dry_run_firstu warningsu: The '{0}' argument is no longer used and has been ignored.u" Invalid path '{0}' for reject_fileu '{0}' is not an absolute pathuS Parent directory for reject_file '{0}' either does not exist, or is not a directoryi i u -Nu --forwardu -ru
--reject-fileu -ou --outputu -pi uU Invalid format for '-p' CLI option. Consider using the 'strip' option for this state.u --stripu =i����uY Invalid format for '-strip' CLI option. Consider using the 'strip' option for this state.u. The following CLI options are not allowed: {0}u , u file.source_listu salt://uI Ignoring 'saltenv' option in favor of saltenv included in the source URL.u ?saltenv={0}u testu test.pingRe R� Rk Ry R� R� R u# Failed to cache patch file {0}: {1}u file.managed: %sNu failed to download %sc @ sH t j � � } | d k r+ | j | � n t d � | d | d | �S( Nu
file.patcht optionsR� ( t copyR5 R� R) ( t
patch_fileR' R� t
patch_opts( RA t sanitized_options( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt _patchZ s u -p{0}u retcodeu -Ru -fR� u Patch was already applieduM Patch would not apply cleanly, no changes made. Results of dry-run are below.uS Run state again using the reject_file option to save rejects to a persistent file.u coloru
u nestedt
nested_indenti u The patch would be appliedu Patch successfully appliedu Failed to apply patchu- file.patch: Failed to remove temp file %s: %s( u hashu
dry_run_first( u -Nu --forwardu -ru
--reject-fileu -ou --output(5 R4 R R R t whichR R* R. R* R� R� R{ R\ R� R5 Rc R t shlex_splitR� R� R R� R� RG R� t rsplitR R) R_ R Rb R] R^ R Rf R R� t modulest
__module__R� t redact_http_basic_authRH R� RI R8 R( t outputt
out_formatRJ R� t errnot ENOENTR� () RA Re R� Rk Ry R� R� R R' t reject_fileR6 R[ Rh R t is_dirt deprecated_argt reject_file_parentR t max_indext blacklisted_optionst optionR t blacklistedt source_matchR� t source_match_urlt source_match_saltenvt cleanupR) t orig_testR� R� R, t
patch_rejectst patch_outputR* t pre_checkt reverse_passt already_appliedt optsR ( ( RA R+ s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt patch sl �"
c C@ s� t j j | � } i | d 6i d 6} | s9 t | d � St j j | � sa t | d j | � � St d r� | j t | | | � � | S| r� y t d | � Wq� t
k
r� } t | d j | j � � SXn t j j t j j
| � � st | d j | � � St j j | � } t d | | | � | d
<| rc| d
rcd j | � | d <| | d d
<nO | r�| d
r�d j t j j | � r�d n d | � | d <| | d d <n | S( u1
Replicate the 'nix "touch" command to create a new empty
file or update the atime and mtime of an existing file.
Note that if you just want to create a file and don't care about atime or
mtime, you should use ``file.managed`` instead, as it is more
feature-complete. (Just leave out the ``source``/``template``/``contents``
arguments, and it will just create the file and/or check its permissions,
without messing with contents)
name
name of the file
atime
atime of the file
mtime
mtime of the file
makedirs
whether we should create the parent directory/directories in order to
touch the file
Usage:
.. code-block:: yaml
/var/log/httpd/logrotate.empty:
file.touch
.. versionadded:: 0.9.5
u nameu changesu Must provide name to file.touchu* Specified file {0} is not an absolute pathu testRA u Drive {0} is not mappedu' Directory not present to touch file {0}u
file.touchu resultu Created empty file {0}u commentu newu Updated times on {0} {1}u directoryu fileu touched( R R R* R� R� R* R RL R� R( R R+ R{ Rc R� R) ( RA R� R� R0 R R� t extant( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR � s< !
(c
K@ s� t j j | � } t j j | � } i | d 6i d 6d j | | � d 6t d 6}
| se t |
d � St } t j j | � s� t |
d j | � � St j j | � s� t |
d j | � � S| r� t d | � } t d
| � } t d | � } n� t | d | �} | d& k r t d
} n t j
j j � r_| d& k rVt j d j | � � n | } n | d& k r�t d t d | � j d d � � } n t | | � } | r�t |
| � S| d& k r�t d | � } n t j j | � r| rt j j | t j j | � � } n t j j | � rt j j | � r| r�t j j | � r�t j
j j | � }
t j
j j | � } |
| k r�t } d j |
d d g � |
d <q�n | s�t } qt d r| ry t d | � Wqt t f k
r
t |
d j | � � SXqn t d re| rDd j | | � |
d <d& |
d <n d j | � |
d <t |
d <|
S| s�d j | � |
d <t |
d <|
St j j | � } t j j | � s!| ry# t d | d | d | d | � Wq t k
r} t |
d j | j! � � SXq!t |
d j | � � Sn y8t j j | � r�t" j# | | d t �x� t j
j j$ | � D]w \ } } } x1 | D]) } t d t j j | | � | | � qxWx1 | D]) } t d t j j | | � | | � q�WqbWn t" j% | | � i | | 6|
d <| sXt j
j j � r;t d! d" | d# |
d$ | � }
qXt d! | |
| | | � n Wn- t t f k
r�t |
d% j | | � � SX|
S(' u\
If the file defined by the ``source`` option exists on the minion, copy it
to the named path. The file will not be overwritten if it already exists,
unless the ``force`` option is set to ``True``.
.. note::
This state only copies files from one location on a minion to another
location on the same minion. For copying files from the master, use a
:py:func:`file.managed <salt.states.file.managed>` state.
name
The location of the file to copy to
source
The location of the file to copy to the location specified with name
force
If the target location is present then the file will not be moved,
specify "force: True" to overwrite the target file
makedirs
If the target subdirectories don't exist create them
preserve
.. versionadded:: 2015.5.0
Set ``preserve: True`` to preserve user/group ownership and mode
after copying. Default is ``False``. If ``preserve`` is set to ``True``,
then user/group/mode attributes will be ignored.
user
.. versionadded:: 2015.5.0
The user to own the copied file, this defaults to the user salt is
running as on the minion. If ``preserve`` is set to ``True``, then
this will be ignored
group
.. versionadded:: 2015.5.0
The group to own the copied file, this defaults to the group salt is
running as on the minion. If ``preserve`` is set to ``True`` or on
Windows this will be ignored
mode
.. versionadded:: 2015.5.0
The permissions to set on the copied file, aka 644, '0775', '4664'.
If ``preserve`` is set to ``True``, then this will be ignored.
Not supported on Windows.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
subdir
.. versionadded:: 2015.5.0
If the name is a directory then place the file inside the named
directory
.. note::
The copy function accepts paths that are local to the Salt minion.
This function does not support salt://, http://, or the other
additional file paths that are supported by :mod:`states.file.managed
<salt.states.file.managed>` and :mod:`states.file.recurse
<salt.states.file.recurse>`.
u nameu changesu Copied "{0}" to "{1}"u commentu resultu Must provide name to file.copyu* Specified file {0} is not an absolute pathu Source file "{0}" is not presentu
file.get_useru file.get_groupu
file.get_modeR+ u useruH The group argument for {0} has been ignored as this is a Windows system.u file.gid_to_groupu user.infou gidi u u+ - files are identical but force flag is setu testu file.removeu5 Failed to delete "{0}" in preparation for forced moveu' File "{0}" is set to be copied to "{1}"u8 The target file "{0}" exists and will not be overwrittenRA R, R� u Drive {0} is not mappedu' The target directory {0} is not presentRN u file.lchownu file.check_permsR R R� u Failed to copy "{0}" to "{1}"N(& R R R* R* R8 R� R� R� R) R� R5 R R R R� R� RH R� R| R0 R{ R R, R- R t hashutilst get_hashR4 R R� Rc R( R R+ t shutilt copytreeR� R( ( RA Re R� R0 t preserveR+ R, R� t subdirRh R t changedR� t hash1t hash2t dnameR� R� R~ R R� t file_( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt copy_ s� N
"
$$ #
# %
'
.
!c C@ s� t j j | � } t j j | � } i | d 6i d 6d d 6t d 6} | sY t | d � St j j | � s� t | d j | � � St j j | � s� d j | � | d <| St j j | � rDt j j | � rD| s� d j | � | d <t | d <| St d
sDy t
d | � WqAt t f k
r=t | d j | � � SXqDn t d
rrd
j | | � | d <d | d <| St j j | � } t j j | � s�| r�y t d | � Wq�t k
r�} t | d j | j � � SXq�t | d j | � � Sn yU t j j | � r9t j | � } t j | | � t j | � n t j | | � Wn- t t f k
ryt | d j | | � � SXd j | | � | d <i | | 6| d <| S( u)
If the source file exists on the system, rename it to the named file. The
named file will not be overwritten if it already exists unless the force
option is set to True.
name
The location of the file to rename to
source
The location of the file to move to the location specified with name
force
If the target location is present then the file will not be moved,
specify "force: True" to overwrite the target file
makedirs
If the target subdirectories don't exist create them
u nameu changesu u commentu resultu Must provide name to file.renameu* Specified file {0} is not an absolute pathu5 Source file "{0}" has already been moved out of placeu8 The target file "{0}" exists and will not be overwrittenu testu file.removeu5 Failed to delete "{0}" in preparation for forced moveu& File "{0}" is set to be moved to "{1}"RA u Drive {0} is not mappedu' The target directory {0} is not presentu Failed to move "{0}" to "{1}"u Moved "{0}" to "{1}"N( R R R* R8 R� R� R* R- R4 R R) R R� R5 Rc R{ R( R R+ Rt t readlinkR6 t unlinkRO t move( RA Re R� R0 R RV R� t linkto( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyR� � st
$
c
K@ s* i | d 6i d 6t d 6d d 6} | s5 t | d � S| d k rY t | d <d | d <| St j d g � } t j d g � } | | } g | D] } d
| k r� | ^ q� s� t | d <d j | t d t d
� | d <| St | t j � r� | f } n t | t
� r| f } n t � \ } }
| | k r<i | | <n | |
k rUi |
| <n | |
| k rvg |
| | <n x, | D]$ } |
| | j t j
| � � q}W| | | k r�g | | | <n xP | D]H } | | | | k r�| | | j | � d j | | � | d <q�q�Wt | |
� | S( u
Prepare accumulator which can be used in template in file.managed state.
Accumulator dictionary becomes available in template. It can also be used
in file.blockreplace.
name
Accumulator name
filename
Filename which would receive this accumulator (see file.managed state
documentation about ``name``)
text
String or list for adding in accumulator
require_in / watch_in
One of them required for sure we fill up accumulator before we manage
the file. Probably the same as filename
Example:
Given the following:
.. code-block:: yaml
animals_doing_things:
file.accumulated:
- filename: /tmp/animal_file.txt
- text: ' jumps over the lazy dog.'
- require_in:
- file: animal_file
animal_file:
file.managed:
- name: /tmp/animal_file.txt
- source: salt://animal_file.txt
- template: jinja
One might write a template for ``animal_file.txt`` like the following:
.. code-block:: jinja
The quick brown fox{% for animal in accumulator['animals_doing_things'] %}{{ animal }}{% endfor %}
Collectively, the above states and template file will produce:
.. code-block:: text
The quick brown fox jumps over the lazy dog.
Multiple accumulators can be "chained" together.
.. note::
The 'accumulator' data structure is a Python dictionary.
Do not expect any loop over the keys in a deterministic order!
u nameu changesu resultu u commentu% Must provide name to file.accumulatedu No text supplied for accumulatoru
require_inu watch_inu fileu# Orphaned accumulator {0} in {1}:{2}u __sls__u __id__u0 Accumulator {0} for file {1} was charged by textN( R8 R� R5 R4 R� R| R* R� R R� Ra R# R� t
itervaluesR� R( (
RA RS R Rh R t
require_int watch_inR� R{ R� R� R� R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt accumulated6 sV 9
%
"
c $ K@ s_ d | k r | j d � n t j j | � } i i t d 6d 6i d d 6dD d 6t d 6d
6} i i d 6i d 6} | r� | d j i t d
6� | d
j i t d 6� n i i d 6d d 6| d 6t d 6} | s� t | d � S| st j j | � sd j | � | d <| Sn | j d d � j
� } t g | | f D] } | r:| ^ q:� d k rht | d � S| r�t d | � } n | d# k r�t | d � St j j j � r�| d# k r�t j d | � n | } n d j | � } d j | � } | t k r-i i d 6d j | j � � d 6| d 6t d 6S|
r^| j | i � j t j j j |
� � n | r�| j | i � j t j j j | � � n |
r�t j j | � r�| t k r�i i d 6d j | � d 6| d 6t d 6St j j j | d! � �d } y# t | | | j | i � � } Wn7 t t f k
rS} t | d <d" j | � | d <t SXWd# QX| d# k r�t j j j | | � } | | k r�t | d <d$ j | � | d <| S| } q�q�n" | r�| j d% g � j d& � n t | | | j | i � � } | d' 7} t j j j! | � } t" d( r�t d) d* | d+ d# d, i d- d# d. | d/ | d0 | d1 d# d2 d# d3 d# d4 d# d5 t# d6 | d7 t | � | d <| d r�d# | d <d8 j | � | d <| s�d9 | d d: <q�n t | d <d$ j | � | d <| St d; d* | d< d d= | d+ d# d> i d. | d/ | d0 | d1 d# d5 t# d? | d@ | d2 d# dA | dB | dC | d6 | � S(E u;
Serializes dataset and store it into managed file. Useful for sharing
simple configuration files.
name
The location of the file to create
dataset
The dataset that will be serialized
dataset_pillar
Operates like ``dataset``, but draws from a value stored in pillar,
using the pillar path syntax used in :mod:`pillar.get
<salt.modules.pillar.get>`. This is useful when the pillar value
contains newlines, as referencing a pillar variable using a jinja/mako
template can result in YAML formatting issues due to the newlines
causing indentation mismatches.
.. versionadded:: 2015.8.0
formatter
Write the data as this format. See the list of :py:mod:`serializer
modules <salt.serializers>` for supported output formats.
encoding
If specified, then the specified encoding will be used. Otherwise, the
file will be encoded using the system locale (usually UTF-8). See
https://docs.python.org/3/library/codecs.html#standard-encodings for
the list of available encodings.
.. versionadded:: 2017.7.0
encoding_errors : 'strict'
Error encoding scheme. Default is ```'strict'```.
See https://docs.python.org/2/library/codecs.html#codec-base-classes
for the list of available schemes.
.. versionadded:: 2017.7.0
user
The user to own the directory, this defaults to the user salt is
running as on the minion
group
The group ownership set for the directory, this defaults to the group
salt is running as on the minion
mode
The permissions to set on this file, e.g. ``644``, ``0775``, or
``4664``.
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
.. note::
This option is **not** supported on Windows.
backup
Overrides the default backup mode for this specific file.
makedirs
Create parent directories for destination file.
.. versionadded:: 2014.1.3
show_changes
Output a unified diff of the old file and the new file. If ``False``
return a boolean if any changes were made.
create
Default is True, if create is set to False then the file will only be
managed if the file already exists on the system.
merge_if_exists
Default is False, if merge_if_exists is True then the existing file will
be parsed and the dataset passed in will be merged with the existing
content
.. versionadded:: 2014.7.0
serializer_opts
Pass through options to serializer. For example:
.. code-block:: yaml
/etc/dummy/package.yaml
file.serialize:
- formatter: yaml
- serializer_opts:
- explicit_start: True
- default_flow_style: True
- indent: 4
The valid opts are the additional opts (i.e. not the data being
serialized) for the function used to serialize the data. Documentation
for the these functions can be found in the list below:
- For **yaml**: `yaml.dump()`_
- For **json**: `json.dumps()`_
- For **python**: `pprint.pformat()`_
.. _`yaml.dump()`: https://pyyaml.org/wiki/PyYAMLDocumentation
.. _`json.dumps()`: https://docs.python.org/2/library/json.html#json.dumps
.. _`pprint.pformat()`: https://docs.python.org/2/library/pprint.html#pprint.pformat
deserializer_opts
Like ``serializer_opts`` above, but only used when merging with an
existing file (i.e. when ``merge_if_exists`` is set to ``True``).
The options specified here will be passed to the deserializer to load
the existing data, before merging with the specified data and
re-serializing.
.. code-block:: yaml
/etc/dummy/package.yaml
file.serialize:
- formatter: yaml
- serializer_opts:
- explicit_start: True
- default_flow_style: True
- indent: 4
- deserializer_opts:
- encoding: latin-1
- merge_if_exists: True
The valid opts are the additional opts (i.e. not the data being
deserialized) for the function used to deserialize the data.
Documentation for the these functions can be found in the list below:
- For **yaml**: `yaml.load()`_
- For **json**: `json.loads()`_
.. _`yaml.load()`: https://pyyaml.org/wiki/PyYAMLDocumentation
.. _`json.loads()`: https://docs.python.org/2/library/json.html#json.loads
However, note that not all arguments are supported. For example, when
deserializing JSON, arguments like ``parse_float`` and ``parse_int``
which accept a callable object cannot be handled in an SLS file.
.. versionadded:: 2019.2.0
For example, this state:
.. code-block:: yaml
/etc/dummy/package.json:
file.serialize:
- dataset:
name: naive
description: A package using naive versioning
author: A confused individual <iam@confused.com>
dependencies:
express: '>= 1.2.0'
optimist: '>= 0.1.0'
engine: node 0.4.1
- formatter: json
will manage the file ``/etc/dummy/package.json``:
.. code-block:: json
{
"author": "A confused individual <iam@confused.com>",
"dependencies": {
"express": ">= 1.2.0",
"optimist": ">= 0.1.0"
},
"description": "A package using naive versioning",
"engine": "node 0.4.1",
"name": "naive"
}
u envu default_flow_styleu yaml.serializei u indentu ,u : u
separatorsu sort_keysu json.serializeu yaml.deserializeu json.deserializeu
allow_unicodeu ensure_asciiu changesu u commentu nameu resultu# Must provide name to file.serializeu3 File {0} is not present and is not set for creationu formatteru yamli u7 Only one of 'dataset' and 'dataset_pillar' is permittedu
pillar.getu2 Neither 'dataset' nor 'dataset_pillar' was defineduG The group argument for %s has been ignored as this is a Windows system.u
{0}.serializeu {0}.deserializeu {0} format is not supportedu6 merge_if_exists is not supported for the {0} formatteru ru( Failed to deserialize existing data: {0}Nu$ The file {0} is in the correct stateu warningsuP The 'deserializer_opts' option is ignored unless merge_if_exists is set to True.u
u testu file.check_managed_changesRA Re R� Rk R+ R, R� Rm R� R� R R[ Rp Ry u. Dataset will be serialized and stored into {0}u <show_changes=False>u diffu file.manage_fileR� R R� Rn R0 Ro R RY ( u ,u : ($ RZ R R R* R4 R8 RL R� R R* R R� R) R5 R R R� R� RH R� t __serializers__t
capitalizeR\ Ra t repack_dictlistR R R| R� R t
dictupdatet
merge_recurseR� R� R R_ ( RA t datasett dataset_pillarR+ R, R� Rn R0 Ro Rd t merge_if_existsR RY t serializer_optst deserializer_optsRh t serializer_optionst deserializer_optionsR t formatterR{ t serializer_namet deserializer_namet fhrt
existing_dataR� t merged_dataRp ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt serialize� s �
1
u 0600c
C@ sn t j j | � } i | d 6i d 6d d 6t d 6} | sG t | d � S| d k ret d | � ry d j | � | d <qjt d
| � s� t d r� d j | � | d <d | d <qbt d
| | | | | | | � } qjt d | � \ } } | | f | | f k r"d j | | | � | d <qjt d | d | | | � d } | d sjd j | � | d <qjn| d k r�t d | � r�d j | � | d <qjt d | � s�t d r�d j | � | d <d | d <q�t d
| | | | | | | � } qjt d | � \ } } | | f | | f k r@d j | | | � | d <qjt d | d | | | � d } | d sjd j | � | d <qjn� | d k rWt d | � r�d j | � | d <qjt d | � st d r�d j | � | d <d | d <qTt d
| | | | | | | � } qjt d | d | | | � d } | d sjd j | � | d <qjn d j | � | d <| S( uu
Create a special file similar to the 'nix mknod command. The supported
device types are ``p`` (fifo pipe), ``c`` (character device), and ``b``
(block device). Provide the major and minor numbers when specifying a
character device or block device. A fifo pipe does not require this
information. The command will create the necessary dirs if needed. If a
file of the same name not of the same type/major/minor exists, it will not
be overwritten or unlinked (deleted). This is logically in place as a
safety measure because you can really shoot yourself in the foot here and
it is the behavior of 'nix ``mknod``. It is also important to note that not
just anyone can create special devices. Usually this is only done as root.
If the state is executed as none other than root on a minion, you may
receive a permission error.
name
name of the file
ntype
node type 'p' (fifo pipe), 'c' (character device), or 'b'
(block device)
major
major number of the device
does not apply to a fifo pipe
minor
minor number of the device
does not apply to a fifo pipe
user
owning user of the device/pipe
group
owning group of the device/pipe
mode
permissions on the device/pipe
Usage:
.. code-block:: yaml
/dev/chr:
file.mknod:
- ntype: c
- major: 180
- minor: 31
- user: root
- group: root
- mode: 660
/dev/blk:
file.mknod:
- ntype: b
- major: 8
- minor: 999
- user: root
- group: root
- mode: 660
/dev/fifo:
file.mknod:
- ntype: p
- user: root
- group: root
- mode: 660
.. versionadded:: 0.17.0
u nameu changesu u commentu resultu Must provide name to file.mknodu cu file.file_existsuC File {0} exists and is not a character device. Refusing to continueu file.is_chrdevu testu) Character device {0} is set to be createdu
file.mknodu file.get_devmmuY Character device {0} exists and has a different major/minor {1}/{2}. Refusing to continueu file.check_permsi u, Character device {0} is in the correct stateu bu? File {0} exists and is not a block device. Refusing to continueu file.is_blkdevu% Block device {0} is set to be createduU Block device {0} exists and has a different major/minor {1}/{2}. Refusing to continueu( Block device {0} is in the correct stateu pu< File {0} exists and is not a fifo pipe. Refusing to continueu file.is_fifou" Fifo pipe {0} is set to be createdu% Fifo pipe {0} is in the correct stateuc Node type unavailable: '{0}'. Available node types are character ('c'), block ('b'), and pipe ('p')N( R R R* R4 R� R) R* R R5 (
RA t ntypet majort minorR+ R, R� R t devmajt devmin( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt mknod
s� F
c K@ s� t j d � d j | | � } t d | | � } | d d k r� i d d 6t d 6t d 6} | j d
� r� | d c d | d
7<n | j d � r� | d c d | d 7<n | St S(
u�
Execute the check_cmd logic.
Return a result dict if ``check_cmd`` succeeds (check_cmd == 0)
otherwise return True
u running our check_cmdu {0} {1}u cmd.run_allu retcodei u check_cmd execution failedu commentu
skip_watchu resultu stdoutu
u stderr( RH RI R* R) R8 R4 R| ( t cmdRS R� t _cmdR� R ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyRj � s
u base64u md5c C@ s� i | d 6i d 6t d 6d d 6} | p+ | s= t d � � nm | rX | rX t d � � nR | rg | } nC | r� t d | t � } | t k r� t d � � q� n t d
� � t d | � } | rEt d | � } t d
| | � } ~ t d | | � }
| |
k r i |
d 6| d 6| d <n | d sEd | d <t | d <| Sn t d t k rmd | d <d | d <| St d | | � | d <d | d <| d s�i d d 6t d | | � d 6| d <n | S( u~
Decode an encoded file and write it to disk
.. versionadded:: 2016.3.0
name
Path of the file to be written.
encoded_data
The encoded file. Either this option or ``contents_pillar`` must be
specified.
contents_pillar
A Pillar path to the encoded file. Uses the same path syntax as
:py:func:`pillar.get <salt.modules.pillar.get>`. The
:py:func:`hashutil.base64_encodefile
<salt.modules.hashutil.base64_encodefile>` function can load encoded
content into Pillar. Either this option or ``encoded_data`` must be
specified.
encoding_type : ``base64``
The type of encoding.
checksum : ``md5``
The hashing algorithm to use to generate checksums. Wraps the
:py:func:`hashutil.digest <salt.modules.hashutil.digest>` execution
function.
Usage:
.. code-block:: yaml
write_base64_encoded_string_to_a_file:
file.decode:
- name: /tmp/new_file
- encoding_type: base64
- contents_pillar: mypillar:thefile
# or
write_base64_encoded_string_to_a_file:
file.decode:
- name: /tmp/new_file
- encoding_type: base64
- encoded_data: |
Z2V0IHNhbHRlZAo=
Be careful with multi-line strings that the YAML indentation is correct.
E.g.,
.. code-block:: jinja
write_base64_encoded_string_to_a_file:
file.decode:
- name: /tmp/new_file
- encoding_type: base64
- encoded_data: |
{{ salt.pillar.get('path:to:data') | indent(8) }}
u nameu changesu resultu u commentu@ Specify either the 'encoded_data' or 'contents_pillar' argument.u> Specify only one 'encoded_data' or 'contents_pillar' argument.u
pillar.getu Pillar data not found.u No contents given.u file.file_existsu hashutil.base64_decodestringu hashutil.digestu hashutil.digest_fileu oldu newu File is in the correct state.u testu File is set to be updated.u hashutil.base64_decodefileu File was updated.N( R4 R R) R8 R R5 ( RA t encoded_dataRs t
encoding_typet checksumR R� t dest_existst instrt insumt outsum( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyRb � sJ <"
c
K@ su t |
d | �} i | d 6i d 6t d 6d d 6} t j j j � sS t | d � S| sf t | d � S| j d � r� | j d
� r� t | d � St j j
t j j | � � } | j d � r� t j j
t j j | � � } n | rt j j
t j j | � � } n | r/t j j
t j j | � � } n | d! k rHt
d } n t d
| � swt d � } | swd } qwn g } t d | � }
|
d k r�| j d j | � � n t j j | � s�| j d j | � � n | r d j | � } t | � d k r| d 7} n t | | � St | | | | | | | | � \ } } } t
d rt| | d <| | d <| | d <| St j j t j j | � � s| r�y t d | d | � Wq t k
r�} t | d j | j � � SXqt | d j t j j | � � � Sn t j j | � s't j j | � rs| d! k r(t j j | � r| sat | d j | � � St d | � t j d � n t j j t j j | � � s| r�y t d | � Wqt k
r�} t | d j | j � � SXqt | d j t j j | � � � Sn t j | | � t j d � qs| rZt d | � d | d d <t j d � qst | d j | � � Sn t j j j � � t! j" j# d � } Wd! QX| j$ | � } | j% j& � | j& � k g } | d! k r�| j | j' | k � n | d! k r!| j | j( j& � | j& � k � n | d! k rF| j | j) | k � n | d! k rw| j | j* j& � | j& � k � n t d" | � r7t+ | � s�t j, | � q7t- | | � r�d# j | | � | d <ne t. | | � r
d$ j | | � | d <d% j | � | d d& <n& t/ | d <| d c d' j | | � 7<| Sn t j j0 | � sqyw | | _% | d! k rm| | _' n | d! k r�| | _( n | d! k r�| | _) n | d! k r�| | _* n | j1 � Wn@ t2 t3 j4 f k
r} t/ | d <d( j | | | � | d <| SXd) j | | � | d <| | d d* <t- | | � sqt. | | � snt/ | d <| d c d+ j | � 7<qnqqn | S(, u�
Create a Windows shortcut
If the file already exists and is a shortcut pointing to any location other
than the specified target, the shortcut will be replaced. If it is
a regular file or directory then the state will return False. If the
regular file or directory is desired to be replaced with a shortcut pass
force: True, if it is to be renamed, pass a backupname.
name
The location of the shortcut to create. Must end with either
".lnk" or ".url"
target
The location that the shortcut points to
arguments
Any arguments to pass in the shortcut
working_dir
Working directory in which to execute target
description
Description to set on shortcut
icon_location
Location of shortcut's icon
force
If the name of the shortcut exists and is not a file and
force is set to False, the state will fail. If force is set to
True, the link or directory in the way of the shortcut file
will be deleted to make room for the shortcut, unless
backupname is set, when it will be renamed
backupname
If the name of the shortcut exists and is not a file, it will be
renamed to the backupname. If the backupname already
exists and force is False, the state will fail. Otherwise, the
backupname will be removed first.
makedirs
If the location of the shortcut does not already have a parent
directory then the state will fail, setting makedirs to True will
allow Salt to create the parent directory. Setting this to True will
also create the parent for backupname if necessary.
user
The user to own the file, this defaults to the user salt is running as
on the minion
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it's not enforced.
R+ u nameu changesu resultu u commentu' Shortcuts are only supported on Windowsu" Must provide name to file.shortcutu .lnku .urlu* Name must end with either ".lnk" or ".url"u useru user.infou user.currentu SYSTEMu file.user_to_uidu User {0} does not existu* Specified file {0} is not an absolute pathu . i u .u testRA u Drive {0} is not mappedu+ Directory "{0}" for shortcut is not presentu1 File exists where the backup target {0} should gou file.removeu, Directory does not exist for backup at "{0}"u Shortcut was forcibly replacedu forcedu> Directory or symlink exists where the shortcut "{0}" should beu
WScript.ShellNu file.file_existsu( Shortcut {0} is present and owned by {1}u$ Set ownership of shortcut {0} to {1}u {0}u ownershipu. Failed to set ownership of shortcut {0} to {1}u- Unable to create new shortcut {0} -> {1}: {2}u Created new shortcut {0} -> {1}u newu( , but was unable to set ownership to {0}(5 R� R8 R R R� R� R� R` R R t realpathR* R5 R R) R� R* R� R R� R& R{ Rc R( R R+ Rt R- t timet sleepR� R R R R R R R R R R R R R RJ R R R4 R� t SaveR[ t
pywintypest com_error( RA R� R R R! R" R� R/ R0 R+ Rh R R1 R. R� R3 R4 R5 R� R# R$ R% ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt shortcuto s B
!!!
$
%
u basec C@ s- i i d 6d d 6| d 6t d 6} y t | � } Wn t k
rP d | d <| SX| r� | r� | j t j j j k r� d j t j j j
| � � | d <| S| ry) t d d | d
| d | d | � } Wn! t k
r� } | j
| d <| SX| sd
j | � | d <| Sn i } | j t j j j k r#t j j t j j | j � � } t j j | � r | r�| r�t d | | j d t d � � }
|
| d k r�t | d <d j | |
� | d <n d j | |
| d � | d <| St | d <d j | � | d <| Sq#d j | � | d <| Sn t d | d | �} | r�t d | | j d t d � � } | r�| r�| | d k r�t | d <d j | | � | d <q�q�n d } d � }
|
| | j d � � r1y) t d | d | d
| j d � �} Wq1t k
r-} t j j j
| j � � | d <| SXn | s]d j t j j j
| � � | d <| St d | | j d t d � � } | | k r�i | d 6| d 6| d d <n | r | r | | d k r�t | d <d j | | � | d <n d j | | | d � | d <| St | d <d j | � | d <| S( u�
.. versionadded:: 2017.7.3
Ensures that a file is saved to the minion's cache. This state is primarily
invoked by other states to ensure that we do not re-download a source file
if we do not need to.
name
The URL of the file to be cached. To cache a file from an environment
other than ``base``, either use the ``saltenv`` argument or include the
saltenv in the URL (e.g. ``salt://path/to/file.conf?saltenv=dev``).
.. note::
A list of URLs is not supported, this must be a single URL. If a
local file is passed here, then the state will obviously not try to
download anything, but it will compare a hash if one is specified.
source_hash
See the documentation for this same argument in the
:py:func:`file.managed <salt.states.file.managed>` state.
.. note::
For remote files not originating from the ``salt://`` fileserver,
such as http(s) or ftp servers, this state will not re-download the
file if the locally-cached copy matches this hash. This is done to
prevent unnecessary downloading on repeated runs of this state. To
update the cached copy of a file, it is necessary to update this
hash.
source_hash_name
See the documentation for this same argument in the
:py:func:`file.managed <salt.states.file.managed>` state.
skip_verify
See the documentation for this same argument in the
:py:func:`file.managed <salt.states.file.managed>` state.
.. note::
Setting this to ``True`` will result in a copy of the file being
downloaded from a remote (http(s), ftp, etc.) source each time the
state is run.
saltenv
Used to specify the environment from which to download a file from the
Salt fileserver (i.e. those with ``salt://`` URL).
This state will in most cases not be useful in SLS files, but it is useful
when writing a state or remote-execution module that needs to make sure
that a file at a given URL has been downloaded to the cachedir. One example
of this is in the :py:func:`archive.extracted <salt.states.file.extracted>`
state:
.. code-block:: python
result = __states__['file.cached'](source_match,
source_hash=source_hash,
source_hash_name=source_hash_name,
skip_verify=skip_verify,
saltenv=__env__)
This will return a dictionary containing the state's return data, including
a ``result`` key which will state whether or not the state was successful.
Note that this will not catch exceptions, so it is best used within a
try/except.
Once this state has been run from within another state or remote-execution
module, the actual location of the cached file can be obtained using
:py:func:`cp.is_cached <salt.modules.cp.is_cached>`:
.. code-block:: python
cached = __salt__['cp.is_cached'](source_match, saltenv=__env__)
This function will return the cached path of the file, or an empty string
if the file is not present in the minion cache.
u changesu u commentu nameu resultu- Only URLs or local file paths are valid inputud Unable to verify upstream hash of source file {0}, please set source_hash or set skip_verify to Trueu file.get_source_sumRe R� Rk R[ u� Failed to get source hash from {0}. This may be a bug. If this error persists, please report it and set skip_verify to True to work around it.u
file.get_hashu hash_typeu hsumu2 File {0} is present on the minion and has hash {1}u] File {0} is present on the minion, but the hash ({1}) does not match the specified hash ({2})u! File {0} is present on the minionu% File {0} is not present on the minionu cp.is_cachedu+ File is already cached to {0} with hash {1}c S@ s� | s | r t St j j j j t | � � } | d k r@ t Sy# t j j j | d | �| k SWn t
t t f k
r� t SXd S( u8
This helper is not needed anymore in develop as the fileclient in the
develop branch now has means of skipping a download if the existing
hash matches one passed to cp.cache_file. Remove this helper and the
code that invokes it, once we have merged forward into develop.
t formN(
R8 R R R t
HASHES_REVMAPR| R� R5 RM RN R R� R� ( R R~ R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt
_try_cache0 s #u
cp.cache_fileu: Failed to cache {0}, check minion log for more informationu oldu newu hashuQ File is cached to {0}, but the hash ({1}) does not match the specified hash ({2})u File is cached to {0}N( R4 Rg R. Rh R R R t
REMOTE_PROTOSR* R] R3 R) R Rb t LOCAL_PROTOSR R R� R* R� R| R R8 R5 t __str__( RA R� Rk Ry R[ R t parsedR� R� RB t
local_hasht
local_copyt pre_hashR� t post_hash( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt cachedo s� R
!
c C@ sY i i d 6d d 6| d 6t d 6} y t | � } Wn t k
rP d | d <| SX| j t j j j k r� t j j
t j j | j � � } t | d <d j
| � | d <| St d | d | �} | r8y t j | � Wn/ t k
r } d
j
| | j � � | d <qUXt | d <t | d d <d j
| � | d <n t | d <d
j
| � | d <| S( u
.. versionadded:: 2017.7.3
Ensures that a file is saved to the minion's cache. This state is primarily
invoked by other states to ensure that we do not re-download a source file
if we do not need to.
name
The URL of the file to be cached. To cache a file from an environment
other than ``base``, either use the ``saltenv`` argument or include the
saltenv in the URL (e.g. ``salt://path/to/file.conf?saltenv=dev``).
.. note::
A list of URLs is not supported, this must be a single URL. If a
local file is passed here, the state will take no action.
saltenv
Used to specify the environment from which to download a file from the
Salt fileserver (i.e. those with ``salt://`` URL).
u changesu u commentu nameu resultu- Only URLs or local file paths are valid inputu) File {0} is a local path, no action takenu cp.is_cachedR[ u Failed to delete {0}: {1}u deletedu {0} was deletedu {0} is not cached( R4 Rg R. Rh R R R R� R R R� R* R8 R* R) RJ R� ( RA R[ R R� RB R� R� ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt
not_cached� s8
!
(� t __doc__t
__future__R R R R( R R� t loggingR R1 R? RO R� R� Rd t collectionsR R R R R t salt.loaderR t salt.payloadt salt.utils.datat salt.utils.dateutilst salt.utils.dictupdatet salt.utils.filest salt.utils.hashutilst salt.utils.patht salt.utils.platformt salt.utils.stringutilst salt.utils.templatest salt.utils.urlt salt.utils.versionst salt.exceptionsR t salt.serializersR t
salt.stateR
R R R� R� t salt.utils.win_daclt salt.utils.win_functionst salt.utils.winapit salt.extR t salt.ext.six.movesR t salt.ext.six.moves.urllib.parseR
Rg R� t win32com.clientR t getLoggert __name__RH t
COMMENT_REGEXt objectR] t __func_alias__R R# R( R0 R5 R< R? R4 Rv R� R� R� R� R� R� R� R� R� R� R� R� R� R� R� R R
R R R R& R( R6 R7 RS R� RT R8 R� R� R� R� Rx R� R� R� R> R R� R R� R& RK R RX R� R` Rs Ry Rj Rb R� R� R� ( ( ( s4 /usr/lib/python2.7/site-packages/salt/states/file.pyt <module> s~
u K W � $ 8 > / � 8 ? w � � � � � � � �� � � � nj � � * � �M �^ i � b� p � �
Mini Shell