ansible/network/basics/uri.py

469 lines
16 KiB
Python
Raw Normal View History

2013-02-15 23:32:31 +01:00
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2013, Romeo Theriault <romeot () hawaii.edu>
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
#
# see examples/playbooks/uri.yml
import cgi
2013-02-15 23:32:31 +01:00
import shutil
import tempfile
import datetime
2013-02-15 23:32:31 +01:00
try:
import json
except ImportError:
import simplejson as json
DOCUMENTATION = '''
---
module: uri
short_description: Interacts with webservices
description:
- Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE
HTTP authentication mechanisms.
2013-02-15 23:32:31 +01:00
version_added: "1.1"
options:
url:
description:
- HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path
required: true
default: null
dest:
description:
- path of where to download the file to (if desired). If I(dest) is a
directory, the basename of the file on the remote server will be used.
2013-02-15 23:32:31 +01:00
required: false
default: null
user:
description:
- username for the module to use for Digest, Basic or WSSE authentication.
required: false
default: null
password:
description:
- password for the module to use for Digest, Basic or WSSE authentication.
required: false
default: null
body:
description:
- The body of the http request/response to the web service. If C(body_format) is set
to 'json' it will take an already formated JSON string or convert a data structure
into JSON.
2013-02-15 23:32:31 +01:00
required: false
default: null
body_format:
description:
- The serialization format of the body. When set to json, encodes the
body argument, if needed, and automatically sets the Content-Type header accordingly.
required: false
choices: [ "raw", "json" ]
default: raw
version_added: "2.0"
2013-02-15 23:32:31 +01:00
method:
description:
2015-10-19 16:13:45 +02:00
- The HTTP method of the request or response. It MUST be uppercase.
2013-02-15 23:32:31 +01:00
required: false
choices: [ "GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS", "PATCH", "TRACE", "CONNECT", "REFRESH" ]
2013-02-15 23:32:31 +01:00
default: "GET"
return_content:
description:
- Whether or not to return the body of the request as a "content" key in
the dictionary result. If the reported Content-type is
"application/json", then the JSON is additionally loaded into a key
called C(json) in the dictionary results.
2013-02-15 23:32:31 +01:00
required: false
choices: [ "yes", "no" ]
2013-02-19 00:03:19 +01:00
default: "no"
2013-02-15 23:32:31 +01:00
force_basic_auth:
description:
- The library used by the uri module only sends authentication information when a webservice
2013-02-15 23:32:31 +01:00
responds to an initial request with a 401 status. Since some basic auth services do not properly
send a 401, logins will fail. This option forces the sending of the Basic authentication header
upon initial request.
required: false
choices: [ "yes", "no" ]
2013-02-19 00:03:19 +01:00
default: "no"
2013-02-15 23:32:31 +01:00
follow_redirects:
description:
2014-01-30 01:04:53 +01:00
- Whether or not the URI module should follow redirects. C(all) will follow all redirects.
C(safe) will follow only "safe" redirects, where "safe" means that the client is only
2014-01-30 01:04:53 +01:00
doing a GET or HEAD on the URI to which it is being redirected. C(none) will not follow
any redirects. Note that C(yes) and C(no) choices are accepted for backwards compatibility,
2014-01-30 01:04:53 +01:00
where C(yes) is the equivalent of C(all) and C(no) is the equivalent of C(safe). C(yes) and C(no)
are deprecated and will be removed in some future version of Ansible.
2013-02-15 23:32:31 +01:00
required: false
2014-01-30 01:04:53 +01:00
choices: [ "all", "safe", "none" ]
default: "safe"
2013-02-15 23:32:31 +01:00
creates:
description:
- a filename, when it already exists, this step will not be run.
required: false
removes:
description:
- a filename, when it does not exist, this step will not be run.
required: false
status_code:
description:
- A valid, numeric, HTTP status code that signifies success of the
request. Can also be comma separated list of status codes.
2013-02-15 23:32:31 +01:00
required: false
default: 200
timeout:
description:
- The socket level timeout in seconds
required: false
2013-03-18 04:07:15 +01:00
default: 30
2013-02-15 23:32:31 +01:00
HEADER_:
description:
- Any parameter starting with "HEADER_" is a sent with your request as a header.
For example, HEADER_Content-Type="application/json" would send the header
"Content-Type" along with your request with a value of "application/json".
This option is deprecated as of C(2.1) and may be removed in a future
release. Use I(headers) instead.
2013-02-15 23:32:31 +01:00
required: false
default: null
headers:
description:
- Add custom HTTP headers to a request in the format of a YAML hash
required: false
default: null
version_added: '2.1'
2013-02-15 23:32:31 +01:00
others:
description:
- all arguments accepted by the M(file) module also work here
required: false
validate_certs:
description:
- If C(no), SSL certificates will not be validated. This should only
set to C(no) used on personally controlled sites using self-signed
certificates. Prior to 1.9.2 the code defaulted to C(no).
required: false
default: 'yes'
choices: ['yes', 'no']
version_added: '1.9.2'
notes:
- The dependency on httplib2 was removed in Ansible 2.1
author: "Romeo Theriault (@romeotheriault)"
'''
2013-02-19 00:03:19 +01:00
EXAMPLES = '''
# Check that you can connect (GET) to a page and it returns a status 200
- uri: url=http://www.example.com
2013-02-19 00:03:19 +01:00
# Check that a page returns a status 200 and fail if the word AWESOME is not
# in the page contents.
- action: uri url=http://www.example.com return_content=yes
register: webpage
2013-02-19 00:03:19 +01:00
- action: fail
2015-12-02 21:01:16 +01:00
when: "'AWESOME' not in webpage.content"
2013-02-19 00:03:19 +01:00
2014-04-02 23:32:44 +02:00
# Create a JIRA issue
- uri:
url: https://your.jira.example.com/rest/api/2/issue/
method: POST
user: your_username
password: your_pass
body: "{{ lookup('file','issue.json') }}"
force_basic_auth: yes
status_code: 201
body_format: json
# Login to a form based webpage, then use the returned cookie to
2014-04-02 23:32:44 +02:00
# access the app in later tasks
- uri:
2016-02-28 11:51:17 +01:00
url: https://your.form.based.auth.example.com/index.php
method: POST
body: "name=your_username&password=your_password&enter=Sign%20in"
status_code: 302
HEADER_Content-Type: "application/x-www-form-urlencoded"
register: login
- uri:
url: https://your.form.based.auth.example.com/dashboard.php
method: GET
return_content: yes
HEADER_Cookie: "{{login.set_cookie}}"
2014-03-31 14:32:07 +02:00
# Queue build of a project in Jenkins:
- uri:
url: "http://{{ jenkins.host }}/job/{{ jenkins.job }}/build?token={{ jenkins.token }}"
method: GET
user: "{{ jenkins.user }}"
password: "{{ jenkins.password }}"
force_basic_auth: yes
status_code: 201
2014-04-02 23:32:44 +02:00
2013-02-15 23:32:31 +01:00
'''
def write_file(module, url, dest, content):
# create a tempfile with some test content
fd, tmpsrc = tempfile.mkstemp()
f = open(tmpsrc, 'wb')
try:
f.write(content)
except Exception, err:
os.remove(tmpsrc)
module.fail_json(msg="failed to create temporary content file: %s" % str(err))
f.close()
checksum_src = None
checksum_dest = None
2013-02-15 23:32:31 +01:00
# raise an error if there is no tmpsrc file
if not os.path.exists(tmpsrc):
os.remove(tmpsrc)
module.fail_json(msg="Source %s does not exist" % (tmpsrc))
if not os.access(tmpsrc, os.R_OK):
os.remove(tmpsrc)
module.fail_json( msg="Source %s not readable" % (tmpsrc))
checksum_src = module.sha1(tmpsrc)
2013-02-15 23:32:31 +01:00
# check if there is no dest file
if os.path.exists(dest):
# raise an error if copy has no permission on dest
if not os.access(dest, os.W_OK):
os.remove(tmpsrc)
module.fail_json(msg="Destination %s not writable" % (dest))
2013-02-15 23:32:31 +01:00
if not os.access(dest, os.R_OK):
os.remove(tmpsrc)
module.fail_json(msg="Destination %s not readable" % (dest))
checksum_dest = module.sha1(dest)
2013-02-15 23:32:31 +01:00
else:
if not os.access(os.path.dirname(dest), os.W_OK):
os.remove(tmpsrc)
module.fail_json(msg="Destination dir %s not writable" % (os.path.dirname(dest)))
if checksum_src != checksum_dest:
2013-02-15 23:32:31 +01:00
try:
shutil.copyfile(tmpsrc, dest)
except Exception, err:
os.remove(tmpsrc)
module.fail_json(msg="failed to copy %s to %s: %s" % (tmpsrc, dest, str(err)))
2013-02-15 23:32:31 +01:00
os.remove(tmpsrc)
def url_filename(url):
fn = os.path.basename(urlparse.urlsplit(url)[2])
if fn == '':
return 'index.html'
return fn
def absolute_location(url, location):
"""Attempts to create an absolute URL based on initial URL, and
next URL, specifically in the case of a ``Location`` header.
"""
if '://' in location:
return location
elif location.startswith('/'):
parts = urlparse.urlsplit(url)
base = url.replace(parts[2], '')
return '%s%s' % (base, location)
elif not location.startswith('/'):
base = os.path.dirname(url)
return '%s/%s' % (base, location)
2013-02-15 23:32:31 +01:00
2014-01-30 01:04:53 +01:00
else:
return location
def uri(module, url, dest, body, body_format, method, headers, socket_timeout):
# is dest is set and is a directory, let's check if we get redirected and
# set the filename from that url
redirected = False
redir_info = {}
r = {}
if dest is not None:
# Stash follow_redirects, in this block we don't want to follow
# we'll reset back to the supplied value soon
follow_redirects = module.params['follow_redirects']
module.params['follow_redirects'] = False
dest = os.path.expanduser(dest)
if os.path.isdir(dest):
# first check if we are redirected to a file download
_, redir_info = fetch_url(module, url, data=body,
headers=headers,
method=method,
timeout=socket_timeout)
# if we are redirected, update the url with the location header,
# and update dest with the new url filename
if redir_info['status'] in (301, 302, 303, 307):
url = redir_info['location']
redirected = True
dest = os.path.join(dest, url_filename(url))
# if destination file already exist, only download if file newer
if os.path.exists(dest):
t = datetime.datetime.utcfromtimestamp(os.path.getmtime(dest))
tstamp = t.strftime('%a, %d %b %Y %H:%M:%S +0000')
headers['If-Modified-Since'] = tstamp
# Reset follow_redirects back to the stashed value
module.params['follow_redirects'] = follow_redirects
resp, info = fetch_url(module, url, data=body, headers=headers,
method=method, timeout=socket_timeout)
r['redirected'] = redirected or info['url'] != url
r.update(redir_info)
r.update(info)
try:
content = resp.read()
except AttributeError:
content = ''
return r, content, dest
2013-02-15 23:32:31 +01:00
def main():
argument_spec = url_argument_spec()
argument_spec.update(dict(
dest = dict(required=False, default=None, type='path'),
url_username = dict(required=False, default=None, aliases=['user']),
url_password = dict(required=False, default=None, aliases=['password']),
body = dict(required=False, default=None, type='raw'),
body_format = dict(required=False, default='raw', choices=['raw', 'json']),
method = dict(required=False, default='GET', choices=['GET', 'POST', 'PUT', 'HEAD', 'DELETE', 'OPTIONS', 'PATCH', 'TRACE', 'CONNECT', 'REFRESH']),
return_content = dict(required=False, default='no', type='bool'),
follow_redirects = dict(required=False, default='safe', choices=['all', 'safe', 'none', 'yes', 'no']),
creates = dict(required=False, default=None, type='path'),
removes = dict(required=False, default=None, type='path'),
status_code = dict(required=False, default=[200], type='list'),
timeout = dict(required=False, default=30, type='int'),
headers = dict(required=False, type='dict')
))
2013-02-15 23:32:31 +01:00
module = AnsibleModule(
argument_spec=argument_spec,
2013-02-15 23:32:31 +01:00
check_invalid_arguments=False,
add_file_common_args=True
)
url = module.params['url']
body = module.params['body']
body_format = module.params['body_format'].lower()
2013-02-15 23:32:31 +01:00
method = module.params['method']
dest = module.params['dest']
return_content = module.params['return_content']
2013-02-15 23:32:31 +01:00
creates = module.params['creates']
removes = module.params['removes']
status_code = [int(x) for x in list(module.params['status_code'])]
socket_timeout = module.params['timeout']
2013-02-15 23:32:31 +01:00
dict_headers = module.params['headers']
if body_format == 'json':
# Encode the body unless its a string, then assume it is preformatted JSON
if not isinstance(body, basestring):
body = json.dumps(body)
dict_headers['Content-Type'] = 'application/json'
# Grab all the http headers. Need this hack since passing multi-values is
# currently a bit ugly. (e.g. headers='{"Content-Type":"application/json"}')
2013-02-15 23:32:31 +01:00
for key, value in module.params.iteritems():
if key.startswith("HEADER_"):
skey = key.replace("HEADER_", "")
dict_headers[skey] = value
if creates is not None:
# do not run the command if the line contains creates=filename
# and the filename already exists. This allows idempotence
# of uri executions.
if os.path.exists(creates):
module.exit_json(stdout="skipped, since %s exists" % creates,
changed=False, stderr=False, rc=0)
2013-02-15 23:32:31 +01:00
if removes is not None:
# do not run the command if the line contains removes=filename
# and the filename do not exists. This allows idempotence
# of uri executions.
if not os.path.exists(removes):
module.exit_json(stdout="skipped, since %s does not exist" % removes, changed=False, stderr=False, rc=0)
2013-02-15 23:32:31 +01:00
# Make the request
resp, content, dest = uri(module, url, dest, body, body_format, method,
dict_headers, socket_timeout)
resp['status'] = int(resp['status'])
2013-02-15 23:32:31 +01:00
# Write the file out if requested
if dest is not None:
if resp['status'] == 304:
changed = False
else:
write_file(module, url, dest, content)
# allow file attribute changes
changed = True
module.params['path'] = dest
file_args = module.load_file_common_arguments(module.params)
file_args['path'] = dest
changed = module.set_fs_attributes_if_different(file_args, changed)
resp['path'] = dest
else:
changed = False
2013-02-15 23:32:31 +01:00
# Transmogrify the headers, replacing '-' with '_', since variables dont
# work with dashes.
2013-02-15 23:32:31 +01:00
uresp = {}
for key, value in resp.iteritems():
ukey = key.replace("-", "_")
2013-02-15 23:32:31 +01:00
uresp[ukey] = value
try:
uresp['location'] = absolute_location(url, uresp['location'])
except KeyError:
pass
# Default content_encoding to try
content_encoding = 'utf-8'
if 'content_type' in uresp:
content_type, params = cgi.parse_header(uresp['content_type'])
if 'charset' in params:
content_encoding = params['charset']
u_content = unicode(content, content_encoding, errors='replace')
if content_type.startswith('application/json') or \
content_type.startswith('text/json'):
try:
js = json.loads(u_content)
uresp['json'] = js
except:
pass
else:
u_content = unicode(content, content_encoding, errors='replace')
if resp['status'] not in status_code:
uresp['msg'] = 'Status code was not %s: %s' % (status_code, uresp.get('msg', ''))
module.fail_json(content=u_content, **uresp)
2013-02-15 23:32:31 +01:00
elif return_content:
module.exit_json(changed=changed, content=u_content, **uresp)
2013-02-15 23:32:31 +01:00
else:
module.exit_json(changed=changed, **uresp)
2013-02-15 23:32:31 +01:00
2013-12-02 21:13:49 +01:00
# import module snippets
from ansible.module_utils.basic import *
from ansible.module_utils.urls import *
if __name__ == '__main__':
main()