ANSIBLE.S3(3)                   ANSIBLE MODULES                  ANSIBLE.S3(3)



NAME
       s3 - idempotent S3 module putting a file into S3.

DESCRIPTION
       This module allows the user to dictate the presence of a given file in
       an S3 bucket. If or once the key (file) exists in the bucket, it
       returns a time-expired download URL. This module has a dependency on
       python-boto.

OPTIONS
       aws_access_key
              AWS access key. If not set then the value of the AWS_ACCESS_KEY
              environment variable is used.

       aws_secret_key
              AWS secret key. If not set then the value of the AWS_SECRET_KEY
              environment variable is used.

       bucket Bucket name.(required)

       dest   The destination file path when downloading an object/key with a
              GET operation.(Added in Ansible version 1.3.)


       expiration
              Time limit (in seconds) for the URL generated and returned by
              S3/Walrus when performing a mode=put or mode=geturl operation.
              (default: 600)

       mode   Switches the module behaviour between put (upload), get
              (download), geturl (return download url (Ansible 1.3+), getstr
              (download object as string (1.3+)), create (bucket) and delete
              (bucket).(required)

       object Keyname of the object inside the bucket. Can be used to create
              "virtual directories", see examples.(Added in Ansible version
              1.3.)


       overwrite
              Force overwrite either locally on the filesystem or remotely
              with the object/key. Used with PUT and GET operations. (default:
              yes(Added in Ansible version 1.2.)


       s3_url S3 URL endpoint. If not specified then the S3_URL environment
              variable is used, if that variable is defined.

       src    The source file path when performing a PUT operation.(Added in
              Ansible version 1.3.)

EXAMPLES
       # Simple PUT operation
       - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put
       # Simple GET operation
       - s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get
       # GET/download and overwrite local file (trust remote)
       - s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get
       # GET/download and do not overwrite local file (trust remote)
       - s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get force=false
       # PUT/upload and overwrite remote file (trust local)
       - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put
       # PUT/upload and do not overwrite remote file (trust local)
       - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put force=false
       # Download an object as a string to use else where in your playbook
       - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=getstr
       # Create an empty bucket
       - s3: bucket=mybucket mode=create
       # Create a bucket with key as directory
       - s3: bucket=mybucket object=/my/directory/path mode=create
       # Delete a bucket and all contents
       - s3: bucket=mybucket mode=delete



AUTHOR
       Lester Wade, Ralph Tice

SEE ALSO
       ansible(1), http://ansible.github.com/modules.html#s3



1.4.5                             2014-02-12                     ANSIBLE.S3(3)
