Skip to content

A
ansible
Commit 5c69918d by Jan-Piet Mens
Options

DOCS: standardize on EXAMPLES (a.k.a. Docs-JumboPatch JetLag Edition) 

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted
parent 39aa5e5e
Showing with 914 additions and 628 deletions
docsite/latest/rst/moduledev.rst
......@@ -363,12 +363,9 @@ Include it in your module file like this::
module: modulename
short_description: This is a sentence describing the module
# ... snip ...
examples:
- code: modulename opt1=arg1 opt2=arg2
description: Optional words describing this example
'''
The ``description``, ``notes`` and ``description`` within ``examples``
The ``description``, and ``notes``
support formatting in some of the output formats (e.g. ``rst``, ``man``).
These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()``
for URL, module, italic, and constant-width respectively. It is suggested
......@@ -376,7 +373,7 @@ to use ``C()`` for file and option names, and ``I()`` when referencing
parameters; module names should be specifies as ``M(module)``.
Examples (which typically contain colons, quotes, etc.) are difficult
to format with YAML, so these can (alternatively, or additionally) be
to format with YAML, so these must be
written in plain text in an ``EXAMPLES`` string within the module
like this::
......@@ -385,7 +382,7 @@ like this::
'''
The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
``EXAMPLES`` blob after any existing ``examples`` you may have in the
``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the
YAML ``DOCUMENTATION`` string.
Building & Testing
......
library/cloud/cloudformation
......@@ -72,19 +72,19 @@ author: James S. Martin
'''
EXAMPLES = '''
# Basic task example
tasks:
- name: launch ansible cloudformation example
action: cloudformation >
stack_name="ansible-cloudformation" state=present
region=us-east-1 disable_rollback=yes
template=files/cloudformation-example.json
args:
template_parameters:
KeyName: jmartin
DiskType: ephemeral
InstanceType: m1.small
ClusterSize: 3
# Basic task example
tasks:
- name: launch ansible cloudformation example
action: cloudformation >
stack_name="ansible-cloudformation" state=present
region=us-east-1 disable_rollback=yes
template=files/cloudformation-example.json
args:
template_parameters:
KeyName: jmartin
DiskType: ephemeral
InstanceType: m1.small
ClusterSize: 3
'''
import boto.cloudformation.connection
......
library/cloud/glance_image
......@@ -85,12 +85,12 @@ options:
default: None
is_public:
description:
- Wether the image can be accesed publically
- Wether the image can be accessed publicly
required: false
default: 'yes'
copy_from:
description:
- A url from where the image can be downloaded, mutually exculsive with file parameter
- A url from where the image can be downloaded, mutually exclusive with file parameter
required: false
default: None
timeout:
......@@ -103,14 +103,22 @@ options:
- The path to the file which has to be uploaded, mutually exclusive with copy_from
required: false
default: None
examples:
- code: "glance_image: login_username=admin login_password=passme login_tenant_name=admin name=cirros container_format=bare
disk_format=qcow2 state=present copy_from=http:launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img"
description: "Uploads an image from an http url"
requirements: ["glanceclient", "keystoneclient"]
'''
EXAMPLES = '''
# Upload an image from an HTTP URL
- glance_image: login_username=admin
login_password=passme
login_tenant_name=admin
name=cirros
container_format=bare
disk_format=qcow2
state=present
copy_from=http:launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-disk.img
'''
import time
try:
import glanceclient
......
library/cloud/keystone_user
......@@ -32,7 +32,7 @@ options:
default: 'http://127.0.0.1:35357/v2.0/'
user:
description:
- The name of the user that has to added/removed from openstack
- The name of the user that has to added/removed from OpenStack
required: false
default: None
password:
......@@ -65,17 +65,21 @@ options:
- Indicate desired state of the resource
choices: ['present', 'absent']
default: present
examples:
- code: 'keystone_user: tenant=demo tenant_description="Default Tenant"'
description: Create a tenant
- code: 'keystone_user: user=john tenant=demo password=secrete'
description: Create a user
- code: 'keystone_user: role=admin user=john tenant=demo'
description: Apply the admin role to the john user in the demo tenant
requirements: [ python-keystoneclient ]
author: Lorin Hochstein
'''
EXAMPLES = '''
# Create a tenant
- keystone_user: tenant=demo tenant_description="Default Tenant"
# Create a user
- keystone_user: user=john tenant=demo password=secrete
# Apply the admin role to the john user in the demo tenant
- keystone_user: role=admin user=john tenant=demo
'''
try:
from keystoneclient.v2_0 import client
except ImportError:
......
library/cloud/nova_compute
......@@ -25,7 +25,7 @@ except ImportError:
DOCUMENTATION = '''
---
module: nova_compute
short_description: Create/Delete VM's from OpenStack
short_description: Create/Delete VMs from OpenStack
description:
- Create or Remove virtual machines from Openstack.
options:
......@@ -71,41 +71,45 @@ options:
default: None
flavor_id:
description:
- The id of the flavor in which the new vm has to be created
- The id of the flavor in which the new VM has to be created
required: false
default: 1
key_name:
description:
- The keypair name to be used when creating a vm
- The key pair name to be used when creating a VM
required: false
default: None
security_groups:
description:
- The name of the security group to which the vm should be added
- The name of the security group to which the VM should be added
required: false
default: None
nics:
description:
- A list of network id's to which the vm's interface should be attached
- A list of network id's to which the VM's interface should be attached
required: false
default: None
meta:
description:
- A list of key value pairs that should be provided as a metadata to the new vm
- A list of key value pairs that should be provided as a metadata to the new VM
required: false
default: None
wait:
description:
- If the module should wait for the vm to be created.
- If the module should wait for the VM to be created.
required: false
default: 'yes'
wait_for:
description:
- The amount of time the module should wait for the vm to get into active state
- The amount of time the module should wait for the VM to get into active state
required: false
default: 180
examples:
- code: "nova_compute:
requirements: ["novaclient"]
'''
EXAMPLES = '''
# Creates a new VM and attaches to a network and passes metadata to the instance
- nova_compute:
state: present
login_username: admin
login_password: admin
......@@ -119,10 +123,9 @@ examples:
- net-id: 34605f38-e52a-25d2-b6ec-754a13ffb723
meta:
hostname: test1
group: uge_master"
description: "Creates a new VM and attaches to a network and passes metadata to the instance"
requirements: ["novaclient"]
group: uge_master
'''
def _delete_server(module, nova):
name = None
try:
......
library/cloud/nova_keypair
......@@ -25,9 +25,9 @@ except ImportError:
DOCUMENTATION = '''
---
module: nova_keypair
short_description: Add/Delete keypair from nova
short_description: Add/Delete key pair from nova
description:
- Add or Remove keypair from nova .
- Add or Remove key pair from nova .
options:
login_username:
description:
......@@ -61,7 +61,7 @@ options:
default: present
name:
description:
- Name that has to be given to the keypair
- Name that has to be given to the key pair
required: true
default: None
public_key:
......@@ -70,14 +70,18 @@ options:
required: false
default: None
examples:
- code: "nova_keypair: state=present login_username=admin login_password=admin login_tenant_name=admin name=ansible_key
public_key={{ lookup('file','~/.ssh/id_rsa.pub') }}"
description: "Creates a keypair with the running users public key"
- code: "nova_keypair: state=present login_username=admin login_password=admin login_tenant_name=admin name=ansible_key"
description: "Creates a new keypair and the private key returned after the run."
requirements: ["novaclient"]
'''
EXAMPLES = '''
# Creates a key pair with the running users public key
- nova_keypair: state=present login_username=admin
login_password=admin login_tenant_name=admin name=ansible_key
public_key={{ lookup('file','~/.ssh/id_rsa.pub') }}
# Creates a new key pair and the private key returned after the run.
- nova_keypair: state=present login_username=admin login_password=admin
login_tenant_name=admin name=ansible_key
'''
def main():
module = AnsibleModule(
......
library/cloud/quantum_floating_ip
......@@ -27,9 +27,9 @@ except ImportError:
DOCUMENTATION = '''
---
module: quantum_floating_ip
short_description: Add/Remove floating ip from an instance
short_description: Add/Remove floating IP from an instance
description:
- Add or Remove a floating ip to an instance
- Add or Remove a floating IP to an instance
options:
login_username:
description:
......@@ -63,21 +63,24 @@ options:
default: present
network_name:
description:
- Name of the nework from which ip has to be assigned to vm. Please make sure the network is an external network
- Name of the network from which IP has to be assigned to VM. Please make sure the network is an external network
required: true
default: None
instance_name:
description:
- The name of the instance to which the ip address should be assigned
- The name of the instance to which the IP address should be assigned
required: true
default: None
examples:
- code: "quantum_floating_ip: state=present login_username=admin login_password=admin login_tenant_name=admin
network_name=external_network instance_name=vm1"
description: "Assigns a floating ip to the instance from an external network"
requirements: ["novaclient", "quantumclient", "keystoneclient"]
'''
EXAMPLES = '''
# Assign a floating ip to the instance from an external network
- quantum_floating_ip: state=present login_username=admin login_password=admin
login_tenant_name=admin network_name=external_network
instance_name=vm1
'''
def _get_ksclient(module, kwargs):
try:
kclient = ksclient.Client(username=kwargs.get('login_username'),
......
library/cloud/quantum_floating_ip_associate
......@@ -27,9 +27,9 @@ except ImportError:
DOCUMENTATION = '''
---
module: quantum_floating_ip_associate
short_description: Associate or disassociate a particular floating ip with an instance
short_description: Associate or disassociate a particular floating IP with an instance
description:
- Associates or disassociates a specific floating ip with a particular instance
- Associates or disassociates a specific floating IP with a particular instance
options:
login_username:
description:
......@@ -63,7 +63,7 @@ options:
default: present
instance_name:
description:
- name of the instance to which the public ip should be assigned
- name of the instance to which the public IP should be assigned
required: true
default: None
ip_address:
......@@ -75,8 +75,14 @@ requirements: ["quantumclient", "keystoneclient"]
'''
EXAMPLES = '''
# Associate a specific floating ip with an Instance
quantum_floating_ip_associate: state=present login_username=admin login_password=admin login_tenant_name=admin ip_address=1.1.1.1 instance_name=vm1
# Associate a specific floating IP with an Instance
quantum_floating_ip_associate:
state=present
login_username=admin
login_password=admin
login_tenant_name=admin
ip_address=1.1.1.1
instance_name=vm1
'''
def _get_ksclient(module, kwargs):
......
library/cloud/quantum_network
......@@ -94,19 +94,22 @@ options:
- Wether the state should be marked as up or down
required: false
default: true
examples:
- code: "quantum_network: state=present login_username=admin login_password=admin
provider_network_type=gre login_tenant_name=admin
provider_segmentation_id=1 tenant_name=tenant1 name=t1network"
description: "Createss a GRE nework with tunnel id of 1 for tenant 1"
- code: "quantum_network: state=present login_username=admin login_password=admin
provider_network_type=local login_tenant_name=admin
provider_segmentation_id=1 router_external=yes name=external_network"
description: "Creates an external,public network"
requirements: ["quantumclient", "keystoneclient"]
'''
EXAMPLES = '''
# Creates an external,public network
- quantum_network: state=present login_username=admin login_password=admin
provider_network_type=gre login_tenant_name=admin
provider_segmentation_id=1 tenant_name=tenant1 name=t1network"
# Createss a GRE nework with tunnel id of 1 for tenant 1
- quantum_network: state=present login_username=admin login_password=admin
provider_network_type=local login_tenant_name=admin
provider_segmentation_id=1 router_external=yes name=external_network
'''
_os_keystone = None
_os_tenant_id = None
......
library/cloud/quantum_router
......@@ -79,7 +79,11 @@ requirements: ["quantumclient", "keystoneclient"]
EXAMPLES = '''
# Creates a router for tenant admin
quantum_router: state=present login_username=admin login_password=admin login_tenant_name=admin name=router1"
quantum_router: state=present
login_username=admin
login_password=admin
login_tenant_name=admin
name=router1"
'''
_os_keystone = None
......
library/cloud/quantum_router_gateway
......@@ -45,7 +45,7 @@ options:
default: 'yes'
auth_url:
description:
- The keystone url for authentication
- The keystone URL for authentication
required: false
default: 'http://127.0.0.1:35357/v2.0/'
region_name:
......@@ -68,13 +68,16 @@ options:
- Name of the external network which should be attached to the router.
required: true
default: None
examples:
- code: "quantum_router_gateway: state=present login_username=admin login_password=admin
login_tenant_name=admin router_name=external_router network_name=external_network"
description: "Attaches an external network with a router to allow flow of external traffic"
requirements: ["quantumclient", "keystoneclient"]
'''
EXAMPLES = '''
# Attach an external network with a router to allow flow of external traffic
- quantum_router_gateway: state=present login_username=admin login_password=admin
login_tenant_name=admin router_name=external_router
network_name=external_network
'''
_os_keystone = None
def _get_ksclient(module, kwargs):
try:
......
library/cloud/quantum_router_interface
......@@ -45,7 +45,7 @@ options:
default: 'yes'
auth_url:
description:
- The keystone url for authentication
- The keystone URL for authentication
required: false
default: 'http://127.0.0.1:35357/v2.0/'
region_name:
......@@ -73,13 +73,17 @@ options:
- Name of the tenant whose subnet has to be attached.
required: false
default: None
examples:
- code: "quantum_router_interface: state=present login_username=admin login_password=admin login_tenant_name=admin
tenant_name=tenant1 router_name=external_route subnet_name=t1subnet"
description: "Attach tenant1's subnet to the external router"
requirements: ["quantumclient", "keystoneclient"]
'''
EXAMPLES = '''
# Attach tenant1's subnet to the external router
- quantum_router_interface: state=present login_username=admin
login_password=admin login_tenant_name=admin
tenant_name=tenant1 router_name=external_route subnet_name=t1subnet
'''
_os_keystone = None
_os_tenant_id = None
......
library/cloud/quantum_subnet
......@@ -25,9 +25,9 @@ except ImportError:
DOCUMENTATION = '''
---
module: quantum_subnet
short_description: Add/Remove floating ip from an instance
short_description: Add/Remove floating IP from an instance
description:
- Add or Remove a floating ip to an instance
- Add or Remove a floating IP to an instance
options:
login_username:
description:
......@@ -46,7 +46,7 @@ options:
default: True
auth_url:
description:
- The keystone url for authentication
- The keystone URL for authentication
required: false
default: 'http://127.0.0.1:35357/v2.0/'
region_name:
......@@ -61,12 +61,12 @@ options:
default: present
network_name:
description:
- Name of the nework to which the subnet should be attached
- Name of the network to which the subnet should be attached
required: true
default: None
cidr:
description:
- The cidr representation of the subnet that should be assigned to the subnet
- The CIDR representation of the subnet that should be assigned to the subnet
required: true
default: None
tenant_name:
......@@ -91,22 +91,24 @@ options:
default: None
allocation_pool_start:
description:
- From the subnet pool the starting address from which the ip should be allocated
- From the subnet pool the starting address from which the IP should be allocated
required: false
default: None
allocation_pool_end:
description:
- From the subnet pool the last ip that should be assigned to the virtual machines
- From the subnet pool the last IP that should be assigned to the virtual machines
required: false
default: None
examples:
- code: "quantum_subnet: state=present login_username=admin login_password=admin login_tenant_name=admin tenant_name=tenant1
network_name=network1 name=net1subnet cidr=192.168.0.0/24"
description: "Create a subnet for a tenant with the specified subnet"
requirements: ["quantum", "keystoneclient"]
'''
EXAMPLES = '''
# Create a subnet for a tenant with the specified subnet
- quantum_subnet: state=present login_username=admin login_password=admin
login_tenant_name=admin tenant_name=tenant1
network_name=network1 name=net1subnet cidr=192.168.0.0/24"
'''
_os_keystone = None
_os_tenant_id = None
_os_network_id = None
......
library/cloud/rax
......@@ -19,7 +19,7 @@ DOCUMENTATION = '''
module: rax
short_description: create / delete an instance in Rackspace Public Cloud
description:
- creates / deletes Rackspace Public Cloud instances and optionally waits for it to be 'running'.
- creates / deletes a Rackspace Public Cloud instance and optionally waits for it to be 'running'.
version_added: "1.2"
options:
service:
......@@ -74,19 +74,6 @@ options:
description:
- how long before wait gives up, in seconds
default: 300
examples:
- code: |
- name: Create a server
local_action:
module: rax
creds_file: ~/.raxpub
service: cloudservers
name: rax-test1
flavor: 5
image: b11d9567-e412-4255-96b9-bd63ab23bcfe
wait: yes
state: present
description: "Example from Ansible Playbooks"
requirements: [ "pyrax" ]
author: Jesse Keating
notes:
......@@ -95,6 +82,19 @@ notes:
- RAX_REGION defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
'''
EXAMPLES = '''
- name: Create a server
local_action:
module: rax
creds_file: ~/.raxpub
service: cloudservers
name: rax-test1
flavor: 5
image: b11d9567-e412-4255-96b9-bd63ab23bcfe
wait: yes
state: present
'''
import sys
import time
import os
......
library/cloud/s3
......@@ -17,9 +17,9 @@
DOCUMENTATION = '''
---
module: s3
short_description: idempotent s3 module putting a file into S3.
short_description: 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.
- 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.
version_added: "1.1"
options:
bucket:
......@@ -41,7 +41,7 @@ options:
aliases: []
dest:
description:
- the destination in s3, if different from path
- the destination in S3, if different from path
required: false
default: null
aliases: []
......@@ -53,7 +53,7 @@ options:
aliases: []
overwrite:
description:
- force overwrite if a file with the same name already exists. Does not support files uploaded to s3 with multipart upload.
- force overwrite if a file with the same name already exists. Does not support files uploaded to S3 with multipart upload.
required: false
default: false
version_added: "1.2"
......@@ -63,13 +63,11 @@ author: Lester Wade, Ralph Tice
EXAMPLES = '''
# Simple PUT operation
module: s3
bucket: mybucket
- s3: bucket: mybucket
path: /path/to/file
state: present
# Force and overwrite if checksums don't match
module: s3
bucket: mybucket
- s3: bucket: mybucket
path: /path/to/file
state: present
overwrite: yes
......
library/cloud/virt
......@@ -61,8 +61,7 @@ author: Michael DeHaan, Seth Vidal
EXAMPLES = '''
# a playbook task line:
tasks:
- virt: name=alpha state=running
- virt: name=alpha state=running
# /usr/bin/ansible invocations
ansible host -m virt -a "name=alpha command=status"
......
library/commands/command
......@@ -65,19 +65,23 @@ options:
required: false
default: null
version_added: "0.9"
examples:
- code: "command: /sbin/shutdown -t now"
description: "Example from Ansible Playbooks"
- code: "command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database"
description: "C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this."
notes:
- If you want to run a command through the shell (say you are using C(<),
C(>), C(|), etc), you actually want the M(shell) module instead. The
M(command) module is much more secure as it's not affected by the user's
environment.
- " C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this."
author: Michael DeHaan
'''
EXAMPLES = '''
# Example from Ansible Playbooks
- command: /sbin/shutdown -t now
# Run the command if the specified file does not exist
- command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
'''
def main():
# the command module is the one ansible module that does not take key=value args
......
library/commands/raw
......@@ -27,9 +27,6 @@ description:
available. There is no change handler support for this module.
- This module does not require python on the remote system, much like
the M(script) module.
examples:
- description: Example from C(/usr/bin/ansible) to bootstrap a legacy python 2.4 host
code: "action: raw yum -y install python-simplejson"
notes:
- If you want to execute a command securely and predictably, it may be
better to use the M(command) module instead. Best practices when writing
......@@ -38,3 +35,8 @@ notes:
judgement.
author: Michael DeHaan
'''
EXAMPLES = '''
# Bootstrap a legacy python 2.4 host
- raw: yum -y install python-simplejson
'''
library/commands/script
......@@ -4,12 +4,12 @@ DOCUMENTATION = """
module: script
short_description: Runs a local script on a remote node after transferring it
description:
- The M(script) module takes the script name followed by a list of
space-delimited arguments.
- The pathed local script will be transfered to the remote node and then executed.
- The given script will be processed through the shell environment on the remote node.
- This module does not require python on the remote system, much like
the M(raw) module.
- "The M(script) module takes the script name followed by a list of
space-delimited arguments. "
- "The local script at path will be transfered to the remote node and then executed. "
- "The given script will be processed through the shell environment on the remote node. "
- "This module does not require python on the remote system, much like
the M(raw) module. "
options:
free_form:
description:
......@@ -17,11 +17,12 @@ options:
required: true
default: null
aliases: []
examples:
- description: "Example from Ansible Playbooks"
code: "action: script /some/local/script.sh --some-arguments 1234"
notes:
- It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
author: Michael DeHaan
"""
EXAMPLES = '''
# Example from Ansible Playbooks
- script: /some/local/script.sh --some-arguments 1234
'''
library/commands/shell
......@@ -34,9 +34,6 @@ options:
required: false
default: null
version_added: "0.9"
examples:
- code: "shell: somescript.sh >> somelog.txt"
description: Execute the command in remote shell
notes:
- If you want to execute a command securely and predictably, it may be
better to use the M(command) module instead. Best practices when writing
......@@ -46,3 +43,8 @@ notes:
requirements: [ ]
author: Michael DeHaan
'''
EXAMPLES = '''
# Execute the command in remote shell; stdout goes to the specified file on the remote
- shell: somescript.sh >> somelog.txt
'''
library/database/mongodb_user
......@@ -67,11 +67,6 @@ options:
required: false
default: present
choices: [ "present", "absent" ]
examples:
- code: "mongodb_user: database=burgers name=bob password=12345 state=present"
description: Create 'burgers' database user with name 'bob' and password '12345'.
- code: "mongodb_user: database=burgers name=bob state=absent"
description: Delete 'burgers' database user with name 'bob'.
notes:
- Requires the pymongo Python package on the remote host, version 2.4.2+. This
can be installed using pip or the OS package manager. @see http://api.mongodb.org/python/current/installation.html
......@@ -79,6 +74,14 @@ requirements: [ "pymongo" ]
author: Elliott Foster
'''
EXAMPLES = '''
# Create 'burgers' database user with name 'bob' and password '12345'.
- mongodb_user: database=burgers name=bob password=12345 state=present
# Delete 'burgers' database user with name 'bob'.
- mongodb_user: database=burgers name=bob state=absent
'''
import ConfigParser
try:
from pymongo import MongoClient
......
library/database/mysql_db
......@@ -72,9 +72,6 @@ options:
description:
- Where to dump/get the C(.sql) file
required: false
examples:
- code: "mysql_db: db=bobdata state=present"
description: Create a new database with name 'bobdata'
notes:
- Requires the MySQLdb Python package on the remote host. For Ubuntu, this
is as easy as apt-get install python-mysqldb. (See M(apt).)
......@@ -86,6 +83,11 @@ requirements: [ ConfigParser ]
author: Mark Theunissen
'''
EXAMPLES = '''
# Create a new database with name 'bobdata'
- mysql_db: db=bobdata state=present
'''
import ConfigParser
import os
try:
......
library/database/mysql_user
......@@ -72,15 +72,6 @@ options:
required: false
default: present
choices: [ "present", "absent" ]
examples:
- code: "mysql_user: name=bob password=12345 priv=*.*:ALL state=present"
description: Create database user with name 'bob' and password '12345' with all database privileges
- code: "mysql_user: login_user=root login_password=123456 name=sally state=absent"
description: Ensure no user named 'sally' exists, also passing in the auth credentials.
- code: mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
description: Example privileges string format
- code: "mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock"
description: Example using login_unix_socket to connect to server
notes:
- Requires the MySQLdb Python package on the remote host. For Ubuntu, this
is as easy as apt-get install python-mysqldb.
......@@ -99,9 +90,22 @@ author: Mark Theunissen
'''
EXAMPLES = """
# Create database user with name 'bob' and password '12345' with all database privileges
- mysql_user: name=bob password=12345 priv=*.*:ALL state=present
# Ensure no user named 'sally' exists, also passing in the auth credentials.
- mysql_user: login_user=root login_password=123456 name=sally state=absent
# Example privileges string format
mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
# Example using login_unix_socket to connect to server
- mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock
# Example .my.cnf file for setting the root password
# Note: don't use quotes around the password, because the mysql_user module
# will include them in the password but the mysql client will not
[client]
user=root
password=n<_665{vS43y
......
library/database/postgresql_db
......@@ -80,11 +80,6 @@ options:
required: false
default: present
choices: [ "present", "absent" ]
examples:
- code: "postgresql_db: db=acme"
description: Create a new database with name C(acme)
- code: "postgresql_db: db=acme encoding='UTF-8' lc_collate='de_DE.UTF-8' lc_ctype='de_DE.UTF-8' template='template0'"
description: Create a new database with name C(acme) and specific encoding and locale settings. If a template different from C(template0) is specified, encoding and locale settings must match those of the template.
notes:
- The default authentication assumes that you are either logging in as or sudo'ing to the C(postgres) account on the host.
- This module uses I(psycopg2), a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on
......@@ -93,6 +88,20 @@ requirements: [ psycopg2 ]
author: Lorin Hochstein
'''
EXAMPLES = '''
# Create a new database with name "acme"
- postgresql_db: db=acme
# Create a new database with name "acme" and specific encoding and locale
# settings. If a template different from "template0" is specified, encoding
# and locale settings must match those of the template.
- postgresql_db: db=acme
encoding='UTF-8'
lc_collate='de_DE.UTF-8'
lc_ctype='de_DE.UTF-8'
template='template0'
'''
try:
import psycopg2
import psycopg2.extras
......
library/database/postgresql_user
......@@ -90,17 +90,6 @@ options:
required: false
default: present
choices: [ "present", "absent" ]
examples:
- code: "postgresql_user: db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL"
description: Create django user and grant access to database and products table
- code: "postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER"
description: Create rails user, grant privilege to create other databases and demote rails from super user status
- code: "postgresql_user: db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no"
description: Remove test user privileges from acme
- code: "postgresql_user: db=test user=test priv=ALL state=absent"
description: Remove test user from test database and the cluster
- code: INSERT,UPDATE/table:SELECT/anothertable:ALL
description: Example privileges string format
notes:
- The default authentication assumes that you are either logging in as or
sudo'ing to the postgres account on the host.
......@@ -117,6 +106,23 @@ requirements: [ psycopg2 ]
author: Lorin Hochstein
'''
EXAMPLES = '''
# Create django user and grant access to database and products table
- postgresql_user: db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL
# Create rails user, grant privilege to create other databases and demote rails from super user status
- postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER
# Remove test user privileges from acme
- postgresql_user: db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no
# Remove test user from test database and the cluster
- postgresql_user: db=test user=test priv=ALL state=absent
# Example privileges string format
INSERT,UPDATE/table:SELECT/anothertable:ALL
'''
import re
try:
......
library/database/riak
......@@ -73,15 +73,18 @@ options:
default: kv
aliases: []
choices: ['kv']
examples:
- code: "riak: command=join target_node=riak@10.1.1.1"
description: "Join's a Riak node to another node"
- code: "riak: wait_for_handoffs=yes"
description: "Wait for handoffs to finish. Use with async and poll."
- code: "riak: wait_for_service=kv"
description: "Wait for riak_kv service to startup"
'''
EXAMPLES = '''
# Join's a Riak node to another node
- riak: command=join target_node=riak@10.1.1.1
# Wait for handoffs to finish. Use with async and poll.
- riak: wait_for_handoffs=yes
# Wait for riak_kv service to startup
- riak: wait_for_service=kv
'''
import re
......
library/files/assemble
......@@ -60,12 +60,14 @@ options:
description:
- all arguments accepted by the M(file) module also work here
required: false
examples:
- code: "assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf"
description: "Example from Ansible Playbooks"
author: Stephen Fromm
'''
EXAMPLES = '''
# Example from Ansible Playbooks
- assemble: src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
'''
# ===========================================
# Support method
......
library/files/copy
......@@ -73,19 +73,23 @@ options:
description:
- all arguments accepted by the M(file) module also work here
required: false
examples:
- code: "copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644"
description: "Example from Ansible Playbooks"
- code: "copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes"
description: "Copy a new C(ntp.conf) file into place, backing up the original if it differs from the copied version"
- code: "copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'"
description: "Copy a new C(sudoers) file into place, after passing validation with visudo"
author: Michael DeHaan
notes:
- The "copy" module can't be used to recursively copy directory structures to the target machine. Please see the
"Delegation" section of the Advanced Playbooks documentation for a better approach to recursive copies.
'''
EXAMPLES = '''
# Example from Ansible Playbooks
- copy: src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
# Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version
- copy: src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes
# Copy a new "sudoers" file into place, after passing validation with visudo
- copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'
'''
def main():
module = AnsibleModule(
......
library/files/file
......@@ -120,16 +120,17 @@ options:
version_added: "1.1"
description:
- recursively set the specified file attributes (applies only to state=directory)
examples:
- code: "file: path=/etc/foo.conf owner=foo group=foo mode=0644"
description: Example from Ansible Playbooks
- code: "file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link"
notes:
- See also M(copy), M(template), M(assemble)
requirements: [ ]
author: Michael DeHaan
'''
EXAMPLES = '''
- file: path=/etc/foo.conf owner=foo group=foo mode=0644
- file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
'''
def main():
# FIXME: pass this around, should not use global
......
library/files/ini_file
......@@ -62,15 +62,6 @@ options:
description:
- all arguments accepted by the M(file) module also work here
required: false
examples:
- code: "ini_file: dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=yes"
description: Ensure C(fav=lemonade) is in section C([drinks]) in said file
- code: |
ini_file: dest=/etc/anotherconf
section=drinks
option=temperature
value=cold
backup=yes
notes:
- While it is possible to add an I(option) without specifying a I(value), this makes
no sense.
......@@ -82,6 +73,16 @@ requirements: [ ConfigParser ]
author: Jan-Piet Mens
'''
EXAMPLES = '''
# Ensure "fav=lemonade is in section "[drinks]" in specified file
- ini_file: dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=yes
- ini_file: dest=/etc/anotherconf
section=drinks
option=temperature
value=cold
backup=yes
'''
import ConfigParser
......
library/files/lineinfile
......@@ -114,19 +114,19 @@ options:
"""
EXAMPLES = r"""
lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
- lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"
- lineinfile: dest=/etc/sudoers state=absent regexp="^%wheel"
lineinfile: dest=/etc/hosts regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644
- lineinfile: dest=/etc/hosts regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644
lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"
- lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"
lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"
- lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"
lineinfile: dest=/etc/sudoers state=present regexp='^%wheel' line='%wheel ALL=(ALL) NOPASSWD: ALL'
- lineinfile: dest=/etc/sudoers state=present regexp='^%wheel' line='%wheel ALL=(ALL) NOPASSWD: ALL'
lineinfile: dest=/opt/jboss-as/bin/standalone.conf regexp='^(.*)Xms(\d+)m(.*)$' line='\1Xms${xms}m\3' backrefs=yes
- lineinfile: dest=/opt/jboss-as/bin/standalone.conf regexp='^(.*)Xms(\d+)m(.*)$' line='\1Xms${xms}m\3' backrefs=yes
"""
def write_changes(module,lines,dest):
......
library/files/template
......@@ -45,11 +45,6 @@ options:
description:
- all arguments accepted by the M(file) module also work here
required: false
examples:
- code: "template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644"
description: "Example from Ansible Playbooks"
- code: "action: template src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'"
description: "Copy a new C(sudoers) file into place, after passing validation with visudo"
notes:
- Since Ansible version 0.9, templates are loaded with C(trim_blocks=True).
- 'You can override jinja2 settings by adding a special header to template file.
......@@ -57,3 +52,11 @@ notes:
requirements: []
author: Michael DeHaan
'''
EXAMPLES = '''
# Example from Ansible Playbooks
- template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644
# Copy a new "sudoers file into place, after passing validation with visudo
- action: template src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'
'''
library/inventory/add_host
......@@ -19,11 +19,15 @@ options:
- The groups to add the hostname to, comma separated.
required: false
author: Seth Vidal
examples:
- description: add host to group 'just_created' with variable foo=42
code: add_host hostname=${ip_from_ec2} groups=just_created foo=42
- description: add a host with a non-standard port local to your machines
code: add_host hostname='${new_ip}:${new_port}'
- description: add a host alias that we reach through a tunnel
code: add_host hostname=${new_ip} ansible_ssh_host=${inventory_hostname} ansible_ssh_port=${new_port}'
'''
EXAMPLES = '''
# add host to group 'just_created' with variable foo=42
- add_host: hostname=${ip_from_ec2} groups=just_created foo=42
# add a host with a non-standard port local to your machines
- add_host: hostname='${new_ip}:${new_port}'
# add a host alias that we reach through a tunnel
- add_host: hostname=${new_ip} ansible_ssh_host=${inventory_hostname} ansible_ssh_port=${new_port}'
'''
library/inventory/group_by
......@@ -13,11 +13,13 @@ options:
- The variables whose values will be used as groups
required: true
author: Jeroen Hoekx
examples:
- description: Create groups based on the machine architecture
code: group_by key=${ansible_machine}
- description: Create groups like 'kvm-host'
code: group_by key=${ansible_virtualization_type}-${ansible_virtualization_role}
notes:
- Spaces in group names are converted to dashes '-'.
'''
EXAMPLES = '''
# Create groups based on the machine architecture
- group_by: key=${ansible_machine}
# Create groups like 'kvm-host'
- group_by: key=${ansible_virtualization_type}-${ansible_virtualization_role}
'''
library/messaging/rabbitmq_plugin
......@@ -46,9 +46,11 @@ options:
required: false
default: enabled
choices: [enabled, disabled]
examples:
- code: rabbitmq_plugin names=rabbitmq_management state=enabled
description: Enables the rabbitmq_management plugin
'''
EXAMPLES = '''
# Enables the rabbitmq_management plugin
- rabbitmq_plugin: names=rabbitmq_management state=enabled
'''
class RabbitMqPlugins(object):
......
library/messaging/rabbitmq_user
......@@ -86,9 +86,17 @@ options:
required: false
default: present
choices: [present, absent]
examples:
- code: rabbitmq_user user=joe password=changeme vhost=/ configure_priv=.* read_priv=.* write_priv=.* state=present
description: Add user to server and assign full access control
'''
EXAMPLES = '''
# Add user to server and assign full access control
- rabbitmq_user: user=joe
password=changeme
vhost=/
configure_priv=.*
read_priv=.*
write_priv=.*
state=present
'''
class RabbitMqUser(object):
......
library/messaging/rabbitmq_vhost
......@@ -50,9 +50,11 @@ options:
- The state of vhost
default: present
choices: [present, absent]
examples:
- code: 'rabbitmq_vhost: name=/test state=present'
description: Ensure that the vhost /test exists.
'''
EXAMPLES = '''
# Ensure that the vhost /test exists.
- rabbitmq_vhost: name=/test state=present
'''
class RabbitMqVhost(object):
......
library/monitoring/monit
......@@ -38,13 +38,15 @@ options:
required: true
default: null
choices: [ "present", "started", "stopped", "restarted", "monitored", "unmonitored", "reloaded" ]
examples:
- code: "monit: name=httpd state=started"
description: Manage the state of program I(httpd) to be in I(started) state.
requirements: [ ]
author: Darryl Stoflet
'''
EXAMPLES = '''
# Manage the state of program "httpd" to be in "started" state.
- monit: name=httpd state=started
'''
def main():
arg_spec = dict(
......
library/monitoring/nagios
......@@ -75,31 +75,44 @@ options:
author: Tim Bielawa
requirements: [ "Nagios" ]
examples:
- description: set 30 minutes of apache downtime
code: "nagios: action=downtime minutes=30 service=httpd host=$inventory_hostname"
- description: schedule an hour of HOST downtime
code: "nagios: action=downtime minutes=60 service=host host=$inventory_hostname"
- description: schedule downtime for ALL services on HOST
code: "nagios: action=downtime minutes=45 service=all host=$inventory_hostname"
- description: schedule downtime for a few services
code: "nagios: action=downtime services=frob,foobar,qeuz host=$inventory_hostname"
- description: enable SMART disk alerts
code: "nagios: action=enable_alerts service=smart host=$inventory_hostname"
- description: "two services at once: disable httpd and nfs alerts"
code: "nagios: action=disable_alerts service=httpd,nfs host=$inventory_hostname"
- description: disable HOST alerts
code: "nagios: action=disable_alerts service=host host=$inventory_hostname"
- description: silence ALL alerts
code: "nagios: action=silence host=$inventory_hostname"
- description: unsilence all alerts
code: "nagios: action=unsilence host=$inventory_hostname"
- description: SHUT UP NAGIOS
code: "nagios: action=silence_nagios"
- description: ANNOY ME NAGIOS
code: "nagios: action=unsilence_nagios"
- description: command something
code: "nagios: action=command command='DISABLE_FAILURE_PREDICTION'"
'''
EXAMPLES = '''
# set 30 minutes of apache downtime
- nagios: action=downtime minutes=30 service=httpd host={{ inventory_hostname }}
# schedule an hour of HOST downtime
- nagios: action=downtime minutes=60 service=host host=$inventory_hostname
# schedule downtime for ALL services on HOST
- nagios: action=downtime minutes=45 service=all host=$inventory_hostname
# schedule downtime for a few services
- nagios: action=downtime services=frob,foobar,qeuz host=$inventory_hostname
# enable SMART disk alerts
- nagios: action=enable_alerts service=smart host=$inventory_hostname
# "two services at once: disable httpd and nfs alerts"
- nagios: action=disable_alerts service=httpd,nfs host=$inventory_hostname
# disable HOST alerts
- nagios: action=disable_alerts service=host host=$inventory_hostname
# silence ALL alerts
- nagios: action=silence host=$inventory_hostname
# unsilence all alerts
- nagios: action=unsilence host=$inventory_hostname
# SHUT UP NAGIOS
- nagios: action=silence_nagios
# ANNOY ME NAGIOS
- nagios: action=unsilence_nagios
# command something
- nagios: action=command command='DISABLE_FAILURE_PREDICTION'
'''
import ConfigParser
......
library/net_infrastructure/netscaler
......@@ -73,18 +73,21 @@ options:
default: server
choices: ["server", "service"]
aliases: []
examples:
- code: ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass"
description: "Disable the server"
- code: ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass action=enable"
description: "Enable the server"
- code: ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass name=local:8080 type=service action=disable"
description: "Disable the service local:8080"
requirements: [ "urllib", "urllib2" ]
author: Nandor Sivok
'''
EXAMPLES = '''
# Disable the server
ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass"
# Enable the server
ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass action=enable"
# Disable the service local:8080
ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass name=local:8080 type=service action=disable"
'''
import json
import urllib
......
library/network/slurp
......@@ -33,20 +33,20 @@ options:
required: true
default: null
aliases: []
examples:
- code: |
ansible host -m slurp -a 'src=/tmp/xx'
host | success >> {
"content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=",
"encoding": "base64"
}
description: "Example using C(/usr/bin/ansible)"
notes:
- "See also: M(fetch)"
requirements: []
author: Michael DeHaan
'''
EXAMPLES = '''
ansible host -m slurp -a 'src=/tmp/xx'
host | success >> {
"content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=",
"encoding": "base64"
}
'''
import base64
def main():
......
library/network/uri
......@@ -120,40 +120,41 @@ options:
description:
- all arguments accepted by the M(file) module also work here
required: false
examples:
- code: "uri: url=http://www.awesome.com"
description: "Check that you can connect (GET) to a page and it returns a status 200"
- code: |
action: uri url=http://www.awesome.com return_content=yes
register: webpage
# informational: requirements for nodes
requirements: [ urlparse, httplib2 ]
author: Romeo Theriault
'''
action: fail
when_string: '"AWESOME" not in "${webpage.content}"'
EXAMPLES = '''
# Check that you can connect (GET) to a page and it returns a status 200
- uri: url=http://www.example.com
description: Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents.
# 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
- code: |
action: >
uri url=https://your.jira.server.com/rest/api/2/issue/
method=POST user=your_username password=your_pass
body='$FILE(issue.json)' force_basic_auth=yes
status_code=201 HEADER_Content-Type="application/json"
description: "Create a JIRA issue."
action: fail
when_string: '"AWESOME" not in "${webpage.content}"'
- code: |
action: >
uri url=https://your.form.based.auth.app.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
action: uri url=https://your.form.based.auth.app.com/dashboard.php method=GET return_content=yes HEADER_Cookie="${login.set_cookie}"
description: "Login to a form based webpage, then use the cookie that got returned to access the app in later tasks."
# Create a JIRA issue.
action: >
uri url=https://your.jira.example.com/rest/api/2/issue/
method=POST user=your_username password=your_pass
body='$FILE(issue.json)' force_basic_auth=yes
status_code=201 HEADER_Content-Type="application/json"
# informational: requirements for nodes
requirements: [ urlparse, httplib2 ]
author: Romeo Theriault
action: >
uri url=https://your.form.based.auth.examle.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
# Login to a form based webpage, then use the returned cookie to
# access the app in later tasks.
action: uri url=https://your.form.based.auth.example.com/dashboard.php
method=GET return_content=yes HEADER_Cookie="${login.set_cookie}"
'''
HAS_HTTPLIB2 = True
......
library/notification/mail
......@@ -99,24 +99,26 @@ options:
- The character set of email being sent
default: 'us-ascii'
requred: false
examples:
- description: "Example playbook sending mail to root"
code: "local_action: mail msg='System ${ansible_hostname} has been sucessfully provisioned.'"
- description: Send e-mail to a bunch of users, attaching files
code: |
- local_action: mail
host='127.0.0.1'
port=2025
subject="Ansible-report"
body="Hello, this is an e-mail. I hope you like it ;-)"
from="jane@example.net (Jane Jolie)"
to="John Doe <j.d@example.org>, Suzie Something <sue@example.com>"
cc="Charlie Root <root@localhost>"
attach="/etc/group /tmp/pavatar2.png"
headers=Reply-To=john@example.com|X-Special="Something or other"
charset=utf8
"""
EXAMPLES = '''
# Example playbook sending mail to root
local_action: mail msg='System ${ansible_hostname} has been sucessfully provisioned.'
# Send e-mail to a bunch of users, attaching files
- local_action: mail
host='127.0.0.1'
port=2025
subject="Ansible-report"
body="Hello, this is an e-mail. I hope you like it ;-)"
from="jane@example.net (Jane Jolie)"
to="John Doe <j.d@example.org>, Suzie Something <sue@example.com>"
cc="Charlie Root <root@localhost>"
attach="/etc/group /tmp/pavatar2.png"
headers=Reply-To=john@example.com|X-Special="Something or other"
charset=utf8
'''
import os
import sys
import smtplib
......
library/packaging/apt
......@@ -87,27 +87,38 @@ author: Matthew Williams
notes:
- Three of the upgrade modes (C(full), C(safe) and its alias C(yes)) require C(aptitude), otherwise
C(apt-get) suffices.
examples:
- code: "apt: pkg=foo update_cache=yes"
description: Update repositories cache and install C(foo) package
- code: "apt: pkg=foo state=absent"
description: Remove C(foo) package
- code: "apt: pkg=foo state=present"
description: Install the package C(foo)
- code: "apt: pkg=foo=1.00 state=present"
description: Install the version '1.00' of package C(foo)
- code: "apt: pkg=nginx state=latest default_release=squeeze-backports update_cache=yes"
description: Update the repository cache and update package C(nginx) to latest version using default release C(squeeze-backport)
- code: "apt: pkg=openjdk-6-jdk state=latest install_recommends=no"
description: Install latest version of C(openjdk-6-jdk) ignoring C(install-reccomends)
- code: "apt: upgrade=dist"
description: Update all packages to the latest version
- code: "apt: update_cache=yes"
description: Run the equivalent of C(apt-get update) as a separate step
- code: "apt: update_cache=yes cache_valid_time=3600"
description: Only run C(update_cache=yes) if the last one is more than more than 3600 seconds ago
'''
EXAMPLES = '''
# Update repositories cache and install "foo" package
- apt: pkg=foo update_cache=yes
# Remove "foo" package
- apt: pkg=foo state=absent
# Install the package "foo"
- apt: pkg=foo state=present
# Install the version '1.00' of package "foo"
- apt: pkg=foo=1.00 state=present
# Update the repository cache and update package "nginx" to latest version using default release squeeze-backport
- apt: pkg=nginx state=latest default_release=squeeze-backports update_cache=yes
# Install latest version of "openjdk-6-jdk" ignoring "install-reccomends"
- apt: pkg=openjdk-6-jdk state=latest install_recommends=no
# Update all packages to the latest version
- apt: upgrade=dist
# Run the equivalent of "apt-get update" as a separate step
- apt: update_cache=yes
# Only run "update_cache=yes" if the last one is more than more than 3600 seconds ago
- apt: update_cache=yes cache_valid_time=3600
'''
import traceback
# added to stave off future warnings about apt api
import warnings
......
library/packaging/apt_key
......@@ -48,17 +48,23 @@ options:
default: present
description:
- used to specify if key is being added or revoked
examples:
- code: "apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present"
description: Add an Apt signing key, uses whichever key is at the URL
- code: "apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present"
description: Add an Apt signing key, will not download if present
- code: "apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent"
description: Remove an Apt signing key, uses whichever key is at the URL
- code: "apt_key: id=473041FA state=absent"
description: Remove a Apt specific signing key
'''
EXAMPLES = '''
# Add an Apt signing key, uses whichever key is at the URL
- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present
# Add an Apt signing key, will not download if present
- apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present
# Remove an Apt signing key, uses whichever key is at the URL
- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent
# Remove a Apt specific signing key
- apt_key: id=473041FA state=absent
'''
# FIXME: standardize into module_common
from urllib2 import urlopen, URLError
from traceback import format_exc
......
library/packaging/apt_repository
......@@ -47,14 +47,17 @@ notes:
- This module cannot be used on Debian Squeeze (Version 6) as there is no C(add-apt-repository) in C(python-software-properties)
- A bug in C(apt-add-repository) always adds C(deb) and C(deb-src) types for repositories (see the issue on Launchpad U(https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264)), if a repo doesn't have source information (eg MongoDB repo from 10gen) the system will fail while updating repositories.
author: Matt Wright
examples:
- code: "apt_repository: repo=ppa:nginx/stable"
description: Add nginx stable repository from PPA
- code: "apt_repository: repo='deb http://archive.canonical.com/ubuntu hardy partner'"
description: Add specified repository into sources.
requirements: [ python-apt ]
'''
EXAMPLES = '''
# Add nginx stable repository from PPA
- apt_repository: repo=ppa:nginx/stable
# Add specified repository into sources.
- apt_repository: repo='deb http://archive.canonical.com/ubuntu hardy partner'
'''
import platform
try:
......
library/packaging/easy_install
......@@ -57,11 +57,6 @@ options:
C(pyvenv), C(virtualenv), C(virtualenv2).
required: false
default: virtualenv
examples:
- code: "easy_install: name=pip"
description: "Examples from Ansible Playbooks"
- code: "easy_install: name=flask virtualenv=/webapps/myapp/venv"
description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)"
notes:
- Please note that the M(easy_install) module can only install Python
libraries. Thus this module is not able to remove libraries. It is
......@@ -73,6 +68,14 @@ requirements: [ "virtualenv" ]
author: Matt Wright
'''
EXAMPLES = '''
# Examples from Ansible Playbooks
- easy_install: name=pip
# Install Flast into the specified virtualenv.
- easy_install: name=flask virtualenv=/webapps/myapp/venv
'''
def _is_package_installed(module, name, easy_install):
cmd = '%s --dry-run %s' % (easy_install, name)
rc, status_stdout, status_stderr = module.run_command(cmd)
......
library/packaging/macports
......@@ -46,11 +46,11 @@ options:
notes: []
'''
EXAMPLES = '''
macports: name=foo state=present
macports: name=foo state=present update_cache=yes
macports: name=foo state=absent
macports: name=foo state=active
macports: name=foo state=inactive
- macports: name=foo state=present
- macports: name=foo state=present update_cache=yes
- macports: name=foo state=absent
- macports: name=foo state=active
- macports: name=foo state=inactive
'''
......
library/packaging/npm
......@@ -65,21 +65,29 @@ options:
required: false
default: present
choices: [ "present", "absent", "latest" ]
examples:
- code: "npm: name=coffee-script path=/app/location"
description: Install I(coffee-script) node.js package.
- code: "npm: name=coffee-script version=1.6.1 path=/app/location"
description: Install I(coffee-script) node.js package on version 1.6.1.
- code: "npm: name=coffee-script global=yes"
description: Install I(coffee-script) node.js package globally.
- code: "npm: name=coffee-script global=yes state=absent"
description: Remove the globally package I(coffee-script).
- code: "npm: path=/app/location"
description: Install packages based on package.json.
- code: "npm: path=/app/location state=latest"
description: Update packages based on package.json to their latest version.
- code: "npm: path=/app/location executable=/opt/nvm/v0.10.1/bin/npm state=present"
description: Install packages based on package.json using the npm installed with nvm v0.10.1.
'''
EXAMPLES = '''
description: Install "coffee-script" node.js package.
- npm: name=coffee-script path=/app/location
description: Install "coffee-script" node.js package on version 1.6.1.
- npm: name=coffee-script version=1.6.1 path=/app/location
description: Install "coffee-script" node.js package globally.
- npm: name=coffee-script global=yes
description: Remove the globally package "coffee-script".
- npm: name=coffee-script global=yes state=absent
description: Install packages based on package.json.
- npm: path=/app/location
description: Update packages based on package.json to their latest version.
- npm: path=/app/location state=latest
description: Install packages based on package.json using the npm installed with nvm v0.10.1.
- npm: path=/app/location executable=/opt/nvm/v0.10.1/bin/npm state=present
'''
import os
......
library/packaging/openbsd_pkg
......@@ -40,13 +40,17 @@ options:
- C(present) will make sure the package is installed.
C(latest) will make sure the latest version of the package is installed.
C(absent) will make sure the specified package is not installed.
examples:
- description: Make sure nmap is installed
code: "openbsd_pkg: name=nmap state=present"
- description: Make sure nmap is the latest version
code: "openbsd_pkg: name=nmap state=latest"
- description: Make sure nmap is not installed
code: "openbsd_pkg: name=nmap state=absent"
'''
EXAMPLES = '''
# Make sure nmap is installed
- openbsd_pkg: name=nmap state=present
# Make sure nmap is the latest version
- openbsd_pkg: name=nmap state=latest
# Make sure nmap is not installed
- openbsd_pkg: name=nmap state=absent
'''
# select whether we dump additional debug info through syslog
......
library/packaging/opkg
......@@ -45,10 +45,10 @@ options:
notes: []
'''
EXAMPLES = '''
opkg: name=foo state=present
opkg: name=foo state=present update_cache=yes
opkg: name=foo state=absent
opkg: name=foo,bar state=absent
- opkg: name=foo state=present
- opkg: name=foo state=present update_cache=yes
- opkg: name=foo state=absent
- opkg: name=foo,bar state=absent
'''
......
library/packaging/pacman
......@@ -47,16 +47,20 @@ options:
author: Afterburn
notes: []
examples:
- code: "pacman: name=foo state=installed"
description: install package foo
- code: "pacman: name=foo state=absent"
description: remove package foo
- code: "pacman: name=foo,bar state=absent"
description: remove packages foo and bar
- code: "pacman: name=bar, state=installed, update_cache=yes"
description: update the package database (pacman -Syy) and install bar (bar will be the updated if a newer version exists)
'''
EXAMPLES = '''
# Install package foo
- pacman: name=foo state=installed
# Remove package foo
- pacman: name=foo state=absent
# Remove packages foo and bar
- pacman: name=foo,bar state=absent
# Update the package database (pacman -Syy) and install bar (bar will be the updated if a newer version exists)
- pacman: name=bar, state=installed, update_cache=yes
'''
......
library/packaging/pip
......@@ -91,31 +91,41 @@ options:
required: false
default: null
version_added: "1.0"
examples:
- code: "pip: name=flask"
description: Install I(flask) python package.
- code: "pip: name=flask version=0.8"
description: Install I(flask) python package on version 0.8.
- code: "pip: name='svn+http://myrepo/svn/MyApp#egg=MyApp'"
description: Install I(MyApp) using one of the remote protocols (bzr+,hg+,git+,svn+) or tarballs (zip, gz, bz2) C(pip) supports. You do not have to supply '-e' option in extra_args. For these source names, C(use_mirrors) is ignored and not applicable.
- code: "pip: name=flask virtualenv=/my_app/venv"
description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), inheriting none of the globally installed modules"
- code: "pip: name=flask virtualenv=/my_app/venv virtualenv_site_packages=yes"
description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), inheriting globally installed modules"
- code: "pip: name=flask virtualenv=/my_app/venv virtualenv_command=virtualenv-2.7"
description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), using Python 2.7"
- code: "pip: requirements=/my_app/requirements.txt"
description: Install specified python requirements.
- code: "pip: requirements=/my_app/requirements.txt virtualenv=/my_app/venv"
description: Install specified python requirements in indicated I(virtualenv).
- code: "pip: requirements=/my_app/requirements.txt extra_args='-i https://example.com/pypi/simple'"
description: Install specified python requirements and custom Index URL.
notes:
- Please note that virtualenv (U(http://www.virtualenv.org/)) must be installed on the remote host if the virtualenv parameter is specified.
requirements: [ "virtualenv", "pip" ]
author: Matt Wright
'''
EXAMPLES = '''
# Install (flask) python package.
- pip: name=flask
# Install (flask) python package on version 0.8.
- pip: name=flask version=0.8
# Install (MyApp) using one of the remote protocols (bzr+,hg+,git+,svn+) or tarballs (zip, gz, bz2) (pip) supports. You do not have to supply '-e' option in extra_args. For these source names, (use_mirrors) is ignored and not applicable.
- pip: name='svn+http://myrepo/svn/MyApp#egg=MyApp'
# Install (Flask) into the specified (virtualenv), inheriting none of the globally installed modules
- pip: name=flask virtualenv=/my_app/venv
# Install (Flask) into the specified (virtualenv), inheriting globally installed modules
- pip: name=flask virtualenv=/my_app/venv virtualenv_site_packages=yes
# Install (Flask) into the specified (virtualenv), using Python 2.7
- pip: name=flask virtualenv=/my_app/venv virtualenv_command=virtualenv-2.7
# Install specified python requirements.
- pip: requirements=/my_app/requirements.txt
# Install specified python requirements in indicated (virtualenv).
- pip: requirements=/my_app/requirements.txt virtualenv=/my_app/venv
# Install specified python requirements and custom Index URL.
- pip: requirements=/my_app/requirements.txt extra_args='-i https://example.com/pypi/simple'
'''
def _get_full_name(name, version=None):
if version is None:
......
library/packaging/pkgin
......@@ -40,13 +40,17 @@ options:
default: present
author: Shaun Zinck
notes: []
examples:
- code: "pkgin: name=foo state=present"
description: install package foo"
- code: "pkgin: name=foo state=absent"
description: remove package foo
- code: "pkgin: name=foo,bar state=absent"
description: remove packages foo and bar
'''
EXAMPLES = '''
# install package foo"
- pkgin: name=foo state=present
# remove package foo
- pkgin: name=foo state=absent
# remove packages foo and bar
- pkgin: name=foo,bar state=absent
'''
......
library/packaging/pkgng
......@@ -54,13 +54,14 @@ options:
author: bleader
notes:
- When using pkgsite, be careful that already in cache packages won't be downloaded again.
examples:
- code: "pkgng: name=foo state=present"
description: install package foo"
- code: "pkgng: name=foo state=absent"
description: remove package foo
- code: "pkgng: name=foo,bar state=absent"
description: remove packages foo and bar
'''
EXAMPLES = '''
# Install package foo
- pkgng: name=foo state=present
# Remove packages foo and bar
- pkgng: name=foo,bar state=absent
'''
......
library/packaging/redhat_subscription
......@@ -59,11 +59,17 @@ options:
- Specify a subscription pool name to consume. Regular expressions accepted.
required: False
default: '^$'
examples:
- code: redhat_subscription action=register username=joe_user password=somepass autosubscribe=true
description: Register as user I(joe_user) with password I(somepass) and auto-subscribe to available content.
- code: redhat_subscription action=register activationkey=1-222333444 pool='^(Red Hat Enterprise Server|Red Hat Virtualization)$'
description: Register with activationkey I(1-222333444) and consume subscriptions matching the names I(Red hat Enterprise Server) and I(Red Hat Virtualization)
'''
EXAMPLES = '''
# Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
- redhat_subscription: action=register username=joe_user password=somepass autosubscribe=true
# Register with activationkey (1-222333444) and consume subscriptions matching
# the names (Red hat Enterprise Server) and (Red Hat Virtualization)
- redhat_subscription: action=register
activationkey=1-222333444
pool='^(Red Hat Enterprise Server|Red Hat Virtualization)$'
'''
import os
......
library/packaging/rhn_channel
......@@ -43,7 +43,7 @@ options:
'''
EXAMPLES = '''
rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme
- rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme
'''
import xmlrpclib
......
library/packaging/rhn_register
......@@ -44,22 +44,31 @@ options:
- Optionally specify a list of comma-separated channels to subscribe to upon successful registration.
required: false
default: []
'''
examples:
- code: rhn_register state=absent username=joe_user password=somepass
description: Unregister system from RHN.
- code: rhn_register state=present username=joe_user password=somepass
description: Register as user I(joe_user) with password I(somepass) and auto-subscribe to available content.
- code: rhn_register state=present activationkey=1-222333444 enable_eus=true
description: Register with activationkey I(1-222333444) and enable extended update support.
- code: rhn_register state=present username=joe_user password=somepass server_url=https://xmlrpc.my.satellite/XMLRPC
description: Register as user I(joe_user) with password I(somepass) against a satellite server specified by I(server_url).
- code: rhn_register state=present username=joe_user password=somepass channels=rhel-x86_64-server-6-foo-1,rhel-x86_64-server-6-bar-1
description: Register as user I(joe_user) with password I(somepass) and enable channels I(rhel-x86_64-server-6-foo-1) and I(rhel-x86_64-server-6-bar-1).
EXAMPLES = '''
# Unregister system from RHN.
- code: rhn_register state=absent username=joe_user password=somepass
# Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
- code: rhn_register state=present username=joe_user password=somepass
# Register with activationkey (1-222333444) and enable extended update support.
- code: rhn_register state=present activationkey=1-222333444 enable_eus=true
# Register as user (joe_user) with password (somepass) against a satellite
# server specified by (server_url).
- rhn_register:
state=present
username=joe_user
password=somepass
server_url=https://xmlrpc.my.satellite/XMLRPC
# Register as user (joe_user) with password (somepass) and enable
# channels (rhel-x86_64-server-6-foo-1) and (rhel-x86_64-server-6-bar-1).
- rhn_register: state=present username=joe_user
password=somepass
channels=rhel-x86_64-server-6-foo-1,rhel-x86_64-server-6-bar-1
'''
import sys
......
library/packaging/svr4pkg
......@@ -53,15 +53,20 @@ options:
proxy:
description:
- HTTP[s] proxy to be used if C(src) is a URL.
'''
EXAMPLES = '''
# Install a package from an already copied file
- svr4pkg: name=CSWcommon src=/tmp/cswpkgs.pkg state=present
# Install a package directly from an http site
- svr4pkg: name=CSWpkgutil src=http://get.opencsw.org/now state=present
examples:
- code: svr4pkg name=CSWcommon src=/tmp/cswpkgs.pkg state=present
description: Install a package from an already copied file
- code: 'svr4pkg name=CSWpkgutil src=http://get.opencsw.org/now state=present'
description: Install a package directly from an http site
- code: svr4pkg name=SUNWgnome-sound-recorder state=absent
description: Ensure that a package is not installed.
# Ensure that a package is not installed.
- svr4pkg: name=SUNWgnome-sound-recorder state=absent
'''
import os
import tempfile
......
library/packaging/yum
......@@ -86,17 +86,18 @@ options:
default: "no"
choices: ["yes", "no"]
aliases: []
examples:
- code: yum name=httpd state=latest
- code: yum name=httpd state=removed
- code: yum name=httpd enablerepo=testing state=installed
notes: []
# informational: requirements for nodes
requirements: [ yum, rpm ]
author: Seth Vidal
'''
EXAMPLES = '''
- yum: name=httpd state=latest
- yum: name=httpd state=removed
- yum: name=httpd enablerepo=testing state=installed
'''
def_qf = "%{name}-%{version}-%{release}.%{arch}"
repoquery='/usr/bin/repoquery'
......
library/packaging/zypper
......@@ -60,16 +60,20 @@ options:
choices: [ "yes", "no" ]
aliases: []
examples:
- code: "zypper: name=nmap state=present"
- code: "zypper: name=nmap state=latest"
- code: "zypper: name=nmap state=absent"
notes: []
# informational: requirements for nodes
requirements: [ zypper, rpm ]
author: Patrick Callahan
'''
EXAMPLES = '''
# Install "nmap"
- zypper: name=nmap state=present
# Remove the "nmap" package
- zypper: name=nmap state=absent
'''
# Function used for getting the name of a currently installed package.
def get_current_name(m, name):
cmd = '/bin/rpm -q --qf \'%{NAME}-%{VERSION}\''
......
library/source_control/bzr
......@@ -50,9 +50,11 @@ options:
description:
- If C(yes), any modified files in the working
tree will be discarded.
examples:
- code: "bzr name=bzr+ssh://foosball.example.org/path/to/branch dest=/srv/checkout version=22"
description: Example bzr checkout from Ansible Playbooks
'''
EXAMPLES = '''
# Example bzr checkout from Ansible Playbooks
- bzr: name=bzr+ssh://foosball.example.org/path/to/branch dest=/srv/checkout version=22
'''
import re
......
library/source_control/git
......@@ -73,13 +73,19 @@ options:
- If C(yes), repository will be updated using the supplied
remote. Otherwise the repo will be left untouched.
Prior to 1.2, this was always 'yes' and could not be disabled.
examples:
- code: "git: repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22"
description: Example git checkout from Ansible Playbooks
- code: "git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello"
description: Example read-write git checkout from github
- code: "git: repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout update=no"
description: Example just ensuring the repo checkout exists
'''
EXAMPLES = '''
# Example git checkout from Ansible Playbooks
- git: repo=git://foosball.example.org/path/to/repo.git
dest=/srv/checkout
version=release-0.22
# Example read-write git checkout from github
- git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello
# Example just ensuring the repo checkout exists
- git: repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout update=no
'''
import re
......
library/source_control/hg
......@@ -72,13 +72,15 @@ notes:
C(StrictHostKeyChecking no) in C(.ssh/config) which will accept and authorize the connection
on behalf of the user. However, if you run as a different user such as setting sudo to True),
for example, root will not look at the user .ssh/config setting.
examples:
- code: "hg: repo=https://bitbucket.org/user/repo1 dest=/home/user/repo1 revision=stable purge=yes"
description: Ensure the current working copy is inside the stable branch and deletes untracked files if any.
requirements: [ ]
'''
EXAMPLES = '''
# Ensure the current working copy is inside the stable branch and deletes untracked files if any.
- hg: repo=https://bitbucket.org/user/repo1 dest=/home/user/repo1 revision=stable purge=yes
'''
def _set_hgrc(hgrc, vals):
parser = ConfigParser.SafeConfigParser()
parser.read(hgrc)
......
library/source_control/subversion
......@@ -61,9 +61,11 @@ options:
- --password parameter passed to svn.
required: false
default: null
examples:
- code: "subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout"
description: Checkout subversion repository to specified folder.
'''
EXAMPLES = '''
# Checkout subversion repository to specified folder.
- subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout
'''
import re
......
library/system/authorized_key
......@@ -66,10 +66,13 @@ author: Brad Olson
EXAMPLES = '''
# Example using key data from a local file on the management machine
authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"
- authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"
# Using alternate directory locations:
authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}" path='/etc/ssh/authorized_keys/charlie' manage_dir=no
- authorized_key: user=charlie
key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"
path='/etc/ssh/authorized_keys/charlie'
manage_dir=no
'''
# Makes sure the public key line is present or absent in the user's .ssh/authorized_keys.
......
library/system/cron
......@@ -114,22 +114,29 @@ options:
default: "no"
choices: [ "yes", "no" ]
aliases: []
examples:
- code: 'cron: name="check dirs" hour="5,2" job="ls -alh > /dev/null"'
description: Ensure a job that runs at 2 and 5 exists. Creates an entry like "* 5,2 * * ls -alh > /dev/null"
- code: 'cron: name="an old job" cron job="/some/dir/job.sh" state=absent'
description: 'Ensure an old job is no longer present. Removes any job that is preceded by "#Ansible: an old job" in the crontab'
- code: 'cron: name="a job for reboot" reboot=yes job="/some/job.sh"'
description: 'Creates an entry like "@reboot /some/job.sh"'
- code: 'cron: name="yum autoupdate" weekday="2" minute=0 hour=12 user="root" job="YUMINTERACTIVE=0 /usr/sbin/yum-autoupdate" cron_file=ansible_yum-autoupdate'
requirements:
- cron
author: Dane Summers
updates: Mike Grozak
"""
EXAMPLES = '''
# Ensure a job that runs at 2 and 5 exists.
# Creates an entry like "* 5,2 * * ls -alh > /dev/null"
- cron: name="check dirs" hour="5,2" job="ls -alh > /dev/null"
# Ensure an old job is no longer present. Removes any job that is prefixed
# by "#Ansible: an old job" from the crontab
- cron: name="an old job" cron job="/some/dir/job.sh" state=absent
# Creates an entry like "@reboot /some/job.sh"
- cron: name="a job for reboot" reboot=yes job="/some/job.sh"
- cron: name="yum autoupdate" weekday="2" minute=0 hour=12
user="root" job="YUMINTERACTIVE=0 /usr/sbin/yum-autoupdate"
cron_file=ansible_yum-autoupdate
'''
import re
import tempfile
import os
......
library/system/facter
......@@ -30,14 +30,16 @@ description:
JSON data that can be useful for inventory purposes.
version_added: "0.2"
options: {}
examples:
- code: ansible www.example.net -m facter
description: "Example command-line invocation"
notes: []
requirements: [ "facter", "ruby-json" ]
author: Michael DeHaan
'''
EXAMPLES = '''
# Example command-line invocation
ansible www.example.net -m facter
'''
def main():
module = AnsibleModule(
argument_spec = dict()
......
library/system/filesystem
......@@ -44,15 +44,18 @@ options:
opts:
description:
- List of options to be passed to mkfs command.
examples:
- description: Create a ext2 filesystem on /dev/sdb1.
code: filesystem fstype=ext2 dev=/dev/sdb1
- description: Create a ext4 filesystem on /dev/sdb1 and check disk blocks.
code: filesystem fstype=ext4 dev=/dev/sdb1 opts="-cc"
notes:
- uses mkfs command
'''
EXAMPLES = '''
# Create a ext2 filesystem on /dev/sdb1.
- filesystem: fstype=ext2 dev=/dev/sdb1
# Create a ext4 filesystem on /dev/sdb1 and check disk blocks.
- filesystem: fstype=ext4 dev=/dev/sdb1 opts="-cc"
'''
def main():
module = AnsibleModule(
argument_spec = dict(
......
library/system/group
......@@ -48,12 +48,14 @@ options:
choices: [ "yes", "no" ]
description:
- If I(yes), indicates that the group created is a system group.
examples:
- code: "group: name=somegroup state=present"
description: Example group command from Ansible Playbooks
'''
EXAMPLES = '''
# Example group command from Ansible Playbooks
- group: name=somegroup state=present
'''
import grp
import syslog
import platform
......
library/system/lvg
......@@ -53,19 +53,25 @@ options:
description:
- If yes, allows to remove volume group with logical volumes.
required: false
examples:
- description: Create a volume group on top of /dev/sda1 with physical extent size = 32MB.
code: lvg vg=vg.services pvs=/dev/sda1 pesize=32
- description: Create or resize a volume group on top of /dev/sdb1 and /dev/sdc5.
If, for example, we already have VG vg.services on top of /dev/sdb1, this VG will be extended by /dev/sdc5.
Or if vg.services was created on top of /dev/sda5, we first extend it with /dev/sdb1 and /dev/sdc5, and then reduce by /dev/sda5.
code: lvg vg=vg.services pvs=/dev/sdb1,/dev/sdc5
- description: Remove a volume group with name vg.services.
code: lvg vg=vg.services state=absent
notes:
- module does not modify PE size for already present volume group
'''
EXAMPLES = '''
# Create a volume group on top of /dev/sda1 with physical extent size = 32MB.
- lvg: vg=vg.services pvs=/dev/sda1 pesize=32
# Create or resize a volume group on top of /dev/sdb1 and /dev/sdc5.
# If, for example, we already have VG vg.services on top of /dev/sdb1,
# this VG will be extended by /dev/sdc5. Or if vg.services was created on
# top of /dev/sda5, we first extend it with /dev/sdb1 and /dev/sdc5,
# and then reduce by /dev/sda5.
- lvg: vg=vg.services pvs=/dev/sdb1,/dev/sdc5
# Remove a volume group with name vg.services.
- lvg: vg=vg.services state=absent
'''
def parse_vgs(data):
vgs = []
for line in data.splitlines():
......
library/system/lvol
......@@ -44,19 +44,24 @@ options:
description:
- Control if the logical volume exists.
required: false
examples:
- description: Create a logical volume of 512m.
code: lvol vg=firefly lv=test size=512
- description: Extend the logical volume to 1024m.
code: lvol vg=firefly lv=test size=1024
- description: Reduce the logical volume to 512m
code: lvol vg=firefly lv=test size=512
- description: Remove the logical volume.
code: lvol vg=firefly lv=test state=absent
notes:
- Filesystems on top of the volume are not resized.
'''
EXAMPLES = '''
# Create a logical volume of 512m.
- lvol: vg=firefly lv=test size=512
# Extend the logical volume to 1024m.
- lvol: vg=firefly lv=test size=1024
# Reduce the logical volume to 512m
- lvol: vg=firefly lv=test size=512
# Remove the logical volume.
- lvol: vg=firefly lv=test state=absent
'''
def parse_lvs(data):
lvs = []
for line in data.splitlines():
......
library/system/mount
......@@ -67,18 +67,21 @@ options:
required: true
choices: [ "present", "absent", "mounted", "unmounted" ]
default: null
examples:
- code: "mount: name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro state=present"
description: "Mount DVD read-only"
- code: "mount: name=/srv/disk src='LABEL=SOME_LABEL' state=present"
description: "Mount up device by label"
- code: "mount: name=/home src='UUID=b3e48f45-f933-4c8e-a700-22a159ec9077' opts=noatime state=present"
description: "Mount up device by UUID"
notes: []
requirements: []
author: Seth Vidal
'''
EXAMPLES = '''
# Mount DVD read-only
- mount: name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro state=present
# Mount up device by label
- mount: name=/srv/disk src='LABEL=SOME_LABEL' state=present
# Mount up device by UUID
- mount: name=/home src='UUID=b3e48f45-f933-4c8e-a700-22a159ec9077' opts=noatime state=present
'''
def write_fstab(lines, dest):
......
library/system/ohai
......@@ -30,14 +30,16 @@ description:
I(Ohai) data is a bit more verbose and nested than I(facter).
version_added: "0.6"
options: {}
examples:
- code: ansible webservers -m ohai --tree=/tmp/ohaidata
description: "Retrieve I(ohai) data from all Web servers and store in one-file per host"
notes: []
requirements: [ "ohai" ]
author: Michael DeHaan
'''
EXAMPLES = '''
# Retrieve (ohai) data from all Web servers and store in one-file per host
ansible webservers -m ohai --tree=/tmp/ohaidata
'''
def main():
module = AnsibleModule(
argument_spec = dict()
......
library/system/ping
......@@ -28,12 +28,14 @@ description:
contact. It does not make sense in playbooks, but it is useful from
C(/usr/bin/ansible)
options: {}
examples:
- code: ansible webservers -m ping
description: Test 'webservers' status
author: Michael DeHaan
'''
EXAMPLES = '''
# Test 'webservers' status
ansible webservers -m ping
'''
def main():
module = AnsibleModule(
argument_spec = dict(
......
library/system/seboolean
......@@ -42,15 +42,17 @@ options:
required: true
default: null
choices: [ 'yes', 'no' ]
examples:
- code: "seboolean: name=httpd_can_network_connect state=yes persistent=yes"
description: Set I(httpd_can_network_connect) flag on and keep it persistent across reboots
notes:
- Not tested on any debian based system
requirements: [ ]
author: Stephen Fromm
'''
EXAMPLES = '''
# Set (httpd_can_network_connect) flag on and keep it persistent across reboots
- seboolean: name=httpd_can_network_connect state=yes persistent=yes
'''
try:
import selinux
HAVE_SELINUX=True
......
library/system/selinux
......@@ -42,16 +42,18 @@ options:
- path to the SELinux configuration file, if non-standard
required: false
default: "/etc/selinux/config"
examples:
- code: "selinux: policy=targeted state=enforcing"
- code: "selinux: policy=targeted state=permissive"
- code: "selinux: state=disabled"
notes:
- Not tested on any debian based system
requirements: [ libselinux-python ]
author: Derek Carter <goozbach@friocorte.com>
'''
EXAMPLES = '''
- selinux: policy=targeted state=enforcing
- selinux: policy=targeted state=permissive
- selinux: state=disabled
'''
import os
import re
import sys
......
library/system/service
......@@ -58,21 +58,29 @@ options:
description:
- Additional arguments provided on the command line
aliases: [ 'args' ]
examples:
- description: Example action to start service httpd, if not running
code: "service: name=httpd state=started"
- description: Example action to stop service httpd, if running
code: "service: name=httpd state=stopped"
- description: Example action to restart service httpd, in all cases
code: "service: name=httpd state=restarted"
- description: Example action to reload service httpd, in all cases
code: "service: name=httpd state=reloaded"
- description: Example action to enable service httpd, and not touch the running state
code: "service: name=httpd enabled=yes"
- description: Example action to start service foo, based on running process /usr/bin/foo
code: "service: name=foo pattern=/usr/bin/foo state=started"
- description: Example action to restart network service for interface eth0
code: "service: name=network state=restarted args=eth0"
'''
EXAMPLES = '''
# Example action to start service httpd, if not running
- service: name=httpd state=started
# Example action to stop service httpd, if running
- service: name=httpd state=stopped
# Example action to restart service httpd, in all cases
- service: name=httpd state=restarted
# Example action to reload service httpd, in all cases
- service: name=httpd state=reloaded
# Example action to enable service httpd, and not touch the running state
- service: name=httpd enabled=yes
# Example action to start service foo, based on running process /usr/bin/foo
- service: name=foo pattern=/usr/bin/foo state=started
# Example action to restart network service for interface eth0
- service: name=network state=restarted args=eth0
'''
import platform
......
library/system/sysctl
......@@ -63,18 +63,24 @@ options:
- specifies the absolute path to C(sysctl.conf), if not /etc/sysctl.conf
required: false
default: /etc/sysctl.conf
examples:
- code: "sysctl: name=vm.swappiness value=5 state=present"
description: "Set vm.swappiness to 5 in /etc/sysctl.conf"
- code: "sysctl: name=kernel.panic state=absent sysctl_file=/etc/sysctl.conf"
description: "Remove kernel.panic entry from /etc/sysctl.conf"
- code: "sysctl: name=kernel.panic value=3 sysctl_file=/tmp/test_sysctl.conf check=before reload=no"
description: Set kernel.panic to 3 in /tmp/test_sysctl.conf, check if the sysctl key seems writable, but do not reload sysctl, and do not check kernel value after (not needed, because not the real /etc/sysctl.conf updated)
notes: []
requirements: []
author: David "DaviXX" CHANIAL <david.chanial@gmail.com>
'''
EXAMPLES = '''
# Set vm.swappiness to 5 in /etc/sysctl.conf
- sysctl: name=vm.swappiness value=5 state=present
# Remove kernel.panic entry from /etc/sysctl.conf
- sysctl: name=kernel.panic state=absent sysctl_file=/etc/sysctl.conf
# Set kernel.panic to 3 in /tmp/test_sysctl.conf, check if the sysctl key
# seems writable, but do not reload sysctl, and do not check kernel value
# after (not needed, because not the real /etc/sysctl.conf updated)
- sysctl: name=kernel.panic value=3 sysctl_file=/tmp/test_sysctl.conf check=before reload=no
'''
# ==============================================================
import os
......
library/system/user
......@@ -158,13 +158,17 @@ options:
- Set a passphrase for the SSH key. If no
passphrase is provided, the SSH key will default to
having no passphrase.
examples:
- code: 'user: name=johnd comment="John Doe" uid=1040'
description: "Add the user 'johnd' with a specific uid and a primary group of 'admin'"
- code: "user: name=johnd state=absent remove=yes"
description: "Remove the user 'johnd'"
- code: 'user: name=jsmith generate_ssh_key=yes ssh_key_bits=2048'
description: "Create a 2048-bit SSH key for user jsmith"
'''
EXAMPLES = '''
# Add the user 'johnd' with a specific uid and a primary group of 'admin'
- user: name=johnd comment="John Doe" uid=1040
# Remove the user 'johnd'
- user: name=johnd state=absent remove=yes
# Create a 2048-bit SSH key for user jsmith
- user: name=jsmith generate_ssh_key=yes ssh_key_bits=2048
'''
import os
......
library/system/zfs
......@@ -206,17 +206,24 @@ options:
- The zoned property.
required: False
choices: ['on','off']
examples:
- code: zfs name=rpool/myfs state=present
description: Create a new file system called myfs in pool rpool
- code: zfs name=rpool/myvol state=present volsize=10M
description: Create a new volume called myvol in pool rpool.
- code: zfs name=rpool/myfs@mysnapshot state=present
description: Create a snapshot of rpool/myfs file system.
- code: zfs name=rpool/myfs2 state=present snapdir=enabled
description: Create a new file system called myfs2 with snapdir enabled
author: Johan Wiren
'''
EXAMPLES = '''
# Create a new file system called myfs in pool rpool
- zfs: name=rpool/myfs state=present
# Create a new volume called myvol in pool rpool.
- zfs: name=rpool/myvol state=present volsize=10M
# Create a snapshot of rpool/myfs file system.
- zfs: name=rpool/myfs@mysnapshot state=present
# Create a new file system called myfs2 with snapdir enabled
- zfs: name=rpool/myfs2 state=present snapdir=enabled
'''
import os
class Zfs(object):
......
library/utilities/debug
......@@ -43,13 +43,16 @@ options:
required: false
default: "no"
choices: [ "yes", "no" ]
examples:
- code: |
- action: debug msg="System $inventory_hostname has uuid $ansible_product_uuid"
- action: debug msg="System $inventory_hostname lacks a gateway" fail=yes
only_if: "is_unset('${ansible_default_ipv4.gateway}')"
- action: debug msg="System $inventory_hostname has gateway ${ansible_default_ipv4.gateway}"
only_if: "is_set('${ansible_default_ipv4.gateway}')"
description: "Example that prints the loopback address and gateway for each host"
author: Dag Wieers
'''
EXAMPLES = '''
# Example that prints the loopback address and gateway for each host
- action: debug msg="System $inventory_hostname has uuid $ansible_product_uuid"
- action: debug msg="System $inventory_hostname lacks a gateway" fail=yes
only_if: "is_unset('${ansible_default_ipv4.gateway}')"
- action: debug msg="System $inventory_hostname has gateway ${ansible_default_ipv4.gateway}"
only_if: "is_set('${ansible_default_ipv4.gateway}')"
'''
library/utilities/fail
......@@ -33,12 +33,12 @@ options:
fail will simple bail out with a generic message.
required: false
default: "'Failed as requested from task'"
examples:
- code: |
fail: msg="The system may not be provisioned according to the CMDB status."
only_if: "'$cmdb_status' != 'to-be-staged'"
description: "Example playbook using fail and only_if together"
author: Dag Wieers
'''
EXAMPLES = '''
# Example playbook using fail and only_if together
- fail: msg="The system may not be provisioned according to the CMDB status."
only_if: "'$cmdb_status' != 'to-be-staged'"
'''
library/utilities/pause
......@@ -26,11 +26,15 @@ options:
required: false
default: null
author: Tim Bielawa
examples:
- description: Pause for 5 minutes to build app cache.
code: "pause: minutes=5"
- description: Pause until you can verify updates to an application were successful.
code: "pause:"
- description: A helpful reminder of what to look out for post-update.
code: 'pause: prompt="Make sure org.foo.FooOverload exception is not present"'
'''
EXAMPLES = '''
# Pause for 5 minutes to build app cache.
- pause: minutes=5
# Pause until you can verify updates to an application were successful.
- pause:
# A helpful reminder of what to look out for post-update.
- pause: prompt="Make sure org.foo.FooOverload exception is not present"
'''
library/utilities/set_fact
......@@ -42,10 +42,10 @@ notes:
EXAMPLES = '''
# Example setting host facts using key=value pairs
set_fact: one_fact="something" other_fact="{{ local_var * 2 }}"
- set_fact: one_fact="something" other_fact="{{ local_var * 2 }}"
# Example setting host facts using complex arguments
set_fact:
one_fact: something
other_fact: "{{ local_var * 2 }}"
- set_fact:
one_fact: something
other_fact: "{{ local_var * 2 }}"
'''
library/utilities/wait_for
......@@ -67,7 +67,7 @@ author: Jeroen Hoekx
EXAMPLES = '''
# wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
wait_for: port=8000 delay=10"
- wait_for: port=8000 delay=10"
'''
def main():
......
library/web_infrastructure/django_manage
......@@ -80,22 +80,22 @@ author: Scott Anderson
EXAMPLES = """
# Run cleanup on the application installed in '$django_dir'.
django_manage: command=cleanup app_path=$django_dir
- django_manage: command=cleanup app_path=$django_dir
# Load the $initial_data fixture into the application
django_manage: command=loaddata app_path=$django_dir fixtures=$initial_data
- django_manage: command=loaddata app_path=$django_dir fixtures=$initial_data
#Run syncdb on the application
django_manage: >
command=syncdb
app_path=$django_dir
settings=$settings_app_name
pythonpath=$settings_dir
virtualenv=$virtualenv_dir
database=$mydb
- django_manage: >
command=syncdb
app_path=$django_dir
settings=$settings_app_name
pythonpath=$settings_dir
virtualenv=$virtualenv_dir
database=$mydb
#Run the SmokeTest test case from the main app. Useful for testing deploys.
django_manage command=test app_path=django_dir apps=main.SmokeTest
- django_manage: command=test app_path=django_dir apps=main.SmokeTest
"""
......
library/web_infrastructure/supervisorctl
......@@ -44,7 +44,7 @@ author: Matt Wright
EXAMPLES = '''
# Manage the state of program to be in 'started' state.
supervisorctl: name=my_app state=started
- supervisorctl: name=my_app state=started
'''
def main():
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment