diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index 551dc617264..6a2108a638f 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -44,7 +44,7 @@ .. raw:: html {% for example in examples %} -

@{ example['description'] }@

+ {% if example['description'] %}

@{ example['description'] | html_ify }@

{% endif %}

     @{ example['code'] }@

{% endfor %} diff --git a/library/assemble b/library/assemble index d038b714950..5539552348c 100755 --- a/library/assemble +++ b/library/assemble @@ -23,6 +23,49 @@ import os.path import shutil import tempfile +DOCUMENTATION = ''' +--- +module: assemble +short_description: Assembles a configuration file from fragments +description: + - Assembles a configuration file from fragments. Often a particular + program will take a single configuration file and does not support a + C(conf.d) style structure where it is easy to build up the configuration + from multiple sources. Assemble will take a directory of files that have + already been transferred to the system, and concatenate them together to + produce a destination file. Files are assembled in string sorting order. + Puppet calls this idea I(fragments). +version_added: "0.5" +options: + src: + description: + - An already existing directory full of source files. + required: true + default: null + aliases: [] + dest: + description: + - A file to create using the concatenation of all of the source files. + required: true + default: null + backup: + description: + - Create a backup file (if C(yes)) including the timestamp information so + you can get the original file back if you somehow clobbered it + incorrectly. + required: false + choices: [ "yes", "no" ] + default: "no" + others: + 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 +''' + # =========================================== # Support methods diff --git a/library/authorized_key b/library/authorized_key index 8ecd542f8df..1353459530b 100755 --- a/library/authorized_key +++ b/library/authorized_key @@ -21,6 +21,37 @@ You should have received a copy of the GNU General Public License along with Ansible. If not, see . """ +DOCUMENTATION = ''' +--- +module: authorized_key +short_description: Adds or removes an authorized key for a user from a remote host. +description: + - Adds or removes an authorized key for a user from a remote host. +version_added: "0.5" +options: + user: + description: + - Name of the user who should have access to the remote host + required: true + default: null + aliases: [] + key: + description: + - the SSH public key, as a string + required: true + default: null + state: + description: + - whether the given key should or should not be in the file + required: false + choices: [ "present", "absent" ] + default: "present" +examples: + - code: authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17" + description: "Example from Ansible Playbooks" +author: Brad Olson +''' + # Makes sure the public key line is present or absent in the user's .ssh/authorized_keys. # # Arguments diff --git a/library/command b/library/command index 585ebabd7b3..753aefe5ed4 100755 --- a/library/command +++ b/library/command @@ -25,6 +25,47 @@ import traceback import shlex import os +DOCUMENTATION = ''' +--- +module: command +short_description: Executes a command on a remote node +description: + - The command module takes the command name followed by a list of arguments, space delimited. + - The given command will be executed on all selected nodes. It will not be + processed through the shell, so variables like C($HOME) and operations + like C("<"), C(">"), C("|"), and C("&") will not work. As such, all + paths to commands must be fully qualified +options: + free_form: + description: + - the command module takes a free form command to run + required: true + default: null + aliases: [] + creates: + description: + - a filename, when it already exists, this step will B(not) be run. + required: no + default: null + chdir: + description: + - cd into this directory before running the command + version_added: "0.6" + required: false + default: null +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: "I(creates) and I(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. +author: Michael DeHaan +''' + def main(): # the command module is the one ansible module that does not take key=value args diff --git a/library/copy b/library/copy index de5ebcf4097..c92bcbdc3f8 100755 --- a/library/copy +++ b/library/copy @@ -22,6 +22,44 @@ import os import shutil import time +DOCUMENTATION = ''' +--- +module: copy +short_description: Copies files to remote locations. +description: + - The M(copy) module copies a file on the local box to remote locations. +options: + src: + description: + - Local path to a file to copy to the remote server; can be absolute or relative. + required: true + default: null + aliases: [] + dest: + description: + - Remote absolute path where the file should be copied to. + required: true + default: null + backup: + description: + - Create a backup file including the timestamp information so you can get + the original file back if you somehow clobbered it incorrectly. + version_added: "0.7" + required: false + choices: [ "yes", "no" ] + default: "no" + others: + 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" +author: Michael DeHaan +''' + def main(): module = AnsibleModule(