PageRenderTime 16ms CodeModel.GetById 7ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/docsite/rst/intro_adhoc.rst

https://github.com/ajanthanm/ansible
ReStructuredText | 279 lines | 181 code | 98 blank | 0 comment | 0 complexity | 9dc9c9f15d50f83579ca76f9e5603832 MD5 | raw file
  1Introduction To Ad-Hoc Commands
  2===============================
  3
  4.. contents:: Topics
  5
  6.. highlight:: bash
  7
  8The following examples show how to use `/usr/bin/ansible` for running
  9ad hoc tasks. 
 10
 11What's an ad-hoc command?
 12
 13An ad-hoc command is something that you might type in to do something really
 14quick, but don't want to save for later.   
 15
 16This is a good place to start to understand the basics of what Ansible can do
 17prior to learning the playbooks language -- ad-hoc commands can also be used
 18to do quick things that you might not necessarily want to write a full playbook 
 19for.  
 20
 21Generally speaking, the true power of Ansible lies in playbooks.
 22Why would you use ad-hoc tasks versus playbooks?
 23
 24For instance, if you wanted to power off all of your lab for Christmas vacation,
 25you could execute a quick one-liner in Ansible without writing a playbook.
 26
 27For configuration management and deployments, though, you'll want to pick up on
 28using '/usr/bin/ansible-playbook' -- the concepts you will learn here will 
 29port over directly to the playbook language.
 30
 31(See :doc:`playbooks` for more information about those)
 32
 33If you haven't read :doc:`intro_inventory` already, please look that over a bit first
 34and then we'll get going.
 35
 36.. _parallelism_and_shell_commands:
 37
 38Parallelism and Shell Commands
 39``````````````````````````````
 40
 41Arbitrary example.
 42
 43Let's use Ansible's command line tool to reboot all web servers in Atlanta, 10 at a time.  First, let's
 44set up SSH-agent so it can remember our credentials::
 45
 46    $ ssh-agent bash
 47    $ ssh-add ~/.ssh/id_rsa
 48
 49If you don't want to use ssh-agent and want to instead SSH with a
 50password instead of keys, you can with ``--ask-pass`` (``-k``), but
 51it's much better to just use ssh-agent.
 52
 53Now to run the command on all servers in a group, in this case,
 54*atlanta*, in 10 parallel forks::
 55
 56    $ ansible atlanta -a "/sbin/reboot" -f 10
 57
 58/usr/bin/ansible will default to running from your user account.  If you do not like this
 59behavior, pass in "-u username".  If you want to run commands as a different user, it looks like this::
 60
 61    $ ansible atlanta -a "/usr/bin/foo" -u username
 62
 63Often you'll not want to just do things from your user account.  If you want to run commands through sudo::
 64
 65    $ ansible atlanta -a "/usr/bin/foo" -u username --sudo [--ask-sudo-pass]
 66
 67Use ``--ask-sudo-pass`` (``-K``) if you are not using passwordless
 68sudo.  This will interactively prompt you for the password to use.
 69Use of passwordless sudo makes things easier to automate, but it's not
 70required.
 71
 72It is also possible to sudo to a user other than root using
 73``--sudo-user`` (``-U``)::
 74
 75    $ ansible atlanta -a "/usr/bin/foo" -u username -U otheruser [--ask-sudo-pass]
 76
 77.. note::
 78   
 79    Rarely, some users have security rules where they constrain their sudo environment to running specific command paths only.  
 80    This does not work with ansible's no-bootstrapping philosophy and hundreds of different modules.
 81    If doing this, use Ansible from a special account that does not have this constraint.  
 82    One way of doing this without sharing access to unauthorized users would be gating Ansible with :doc:`tower`, which
 83    can hold on to an SSH credential and let members of certain organizations use it on their behalf without having direct access.
 84
 85Ok, so those are basics.  If you didn't read about patterns and groups yet, go back and read :doc:`intro_patterns`.
 86
 87The ``-f 10`` in the above specifies the usage of 10 simultaneous
 88processes to use.   You can also set this in :doc:`intro_configuration` to avoid setting it again.  The default is actually 5, which
 89is really small and conservative.  You are probably going to want to talk to a lot more simultaneous hosts so feel free
 90to crank this up.  If you have more hosts than the value set for the fork count, Ansible will talk to them, but it will
 91take a little longer.  Feel free to push this value as high as your system can handle it!
 92
 93You can also select what Ansible "module" you want to run.  Normally commands also take a ``-m`` for module name, but
 94the default module name is 'command', so we didn't need to
 95specify that all of the time.  We'll use ``-m`` in later examples to
 96run some other :doc:`modules`.
 97
 98.. note::
 99   The :ref:`command` module does not
100   support shell variables and things like piping.  If we want to execute a module using a
101   shell, use the 'shell' module instead. Read more about the differences on the :doc:`modules`
102   page.
103
104Using the :ref:`shell` module looks like this::
105
106    $ ansible raleigh -m shell -a 'echo $TERM'
107
108When running any command with the Ansible *ad hoc* CLI (as opposed to
109:doc:`Playbooks <playbooks>`), pay particular attention to shell quoting rules, so
110the local shell doesn't eat a variable before it gets passed to Ansible.
111For example, using double vs single quotes in the above example would
112evaluate the variable on the box you were on.
113
114So far we've been demoing simple command execution, but most Ansible modules usually do not work like
115simple scripts. They make the remote system look like you state, and run the commands necessary to
116get it there.  This is commonly referred to as 'idempotence', and is a core design goal of Ansible.
117However, we also recognize that running arbitrary commands is equally important, so Ansible easily supports both.
118
119.. _file_transfer:
120
121File Transfer
122`````````````
123
124Here's another use case for the `/usr/bin/ansible` command line.  Ansible can SCP lots of files to multiple machines in parallel.
125
126To transfer a file directly to many servers::
127
128    $ ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"
129
130If you use playbooks, you can also take advantage of the ``template`` module,
131which takes this another step further.  (See module and playbook documentation).
132
133The ``file`` module allows changing ownership and permissions on files.  These
134same options can be passed directly to the ``copy`` module as well::
135
136    $ ansible webservers -m file -a "dest=/srv/foo/a.txt mode=600"
137    $ ansible webservers -m file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"
138
139The ``file`` module can also create directories, similar to ``mkdir -p``::
140
141    $ ansible webservers -m file -a "dest=/path/to/c mode=755 owner=mdehaan group=mdehaan state=directory"
142
143As well as delete directories (recursively) and delete files::
144
145    $ ansible webservers -m file -a "dest=/path/to/c state=absent"
146
147.. _managing_packages:
148
149Managing Packages
150`````````````````
151
152There are modules available for yum and apt.  Here are some examples
153with yum.
154
155Ensure a package is installed, but don't update it::
156
157    $ ansible webservers -m yum -a "name=acme state=installed"
158
159Ensure a package is installed to a specific version::
160
161    $ ansible webservers -m yum -a "name=acme-1.5 state=installed"
162
163Ensure a package is at the latest version::
164
165    $ ansible webservers -m yum -a "name=acme state=latest"
166
167Ensure a package is not installed::
168
169    $ ansible webservers -m yum -a "name=acme state=removed"
170
171Ansible has modules for managing packages under many platforms.  If your package manager
172does not have a module available for it, you can install
173for other packages using the command module or (better!) contribute a module
174for other package managers.  Stop by the mailing list for info/details.
175
176.. _users_and_groups:
177
178Users and Groups
179````````````````
180
181The 'user' module allows easy creation and manipulation of
182existing user accounts, as well as removal of user accounts that may
183exist::
184
185    $ ansible all -m user -a "name=foo password=<crypted password here>"
186
187    $ ansible all -m user -a "name=foo state=absent"
188
189See the :doc:`modules` section for details on all of the available options, including
190how to manipulate groups and group membership.
191
192.. _from_source_control:
193
194Deploying From Source Control
195`````````````````````````````
196
197Deploy your webapp straight from git::
198
199    $ ansible webservers -m git -a "repo=git://foo.example.org/repo.git dest=/srv/myapp version=HEAD"
200
201Since Ansible modules can notify change handlers it is possible to
202tell Ansible to run specific tasks when the code is updated, such as
203deploying Perl/Python/PHP/Ruby directly from git and then restarting
204apache.
205
206.. _managing_services:
207
208Managing Services
209`````````````````
210
211Ensure a service is started on all webservers::
212
213    $ ansible webservers -m service -a "name=httpd state=started"
214
215Alternatively, restart a service on all webservers::
216
217    $ ansible webservers -m service -a "name=httpd state=restarted"
218
219Ensure a service is stopped::
220
221    $ ansible webservers -m service -a "name=httpd state=stopped"
222
223.. _time_limited_background_operations:
224
225Time Limited Background Operations
226``````````````````````````````````
227
228Long running operations can be backgrounded, and their status can be
229checked on later. The same job ID is given to the same task on all
230hosts, so you won't lose track.  If you kick hosts and don't want
231to poll, it looks like this::
232
233    $ ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff"
234
235If you do decide you want to check on the job status later, you can::
236
237    $ ansible all -m async_status -a "jid=123456789"
238
239Polling is built-in and looks like this::
240
241    $ ansible all -B 1800 -P 60 -a "/usr/bin/long_running_operation --do-stuff"
242
243The above example says "run for 30 minutes max (``-B``: 30*60=1800),
244poll for status (``-P``) every 60 seconds".
245
246Poll mode is smart so all jobs will be started before polling will begin on any machine.
247Be sure to use a high enough ``--forks`` value if you want to get all of your jobs started
248very quickly. After the time limit (in seconds) runs out (``-B``), the process on
249the remote nodes will be terminated.
250
251Typically you'll only be backgrounding long-running
252shell commands or software upgrades only.  Backgrounding the copy module does not do a background file transfer.  :doc:`Playbooks <playbooks>` also support polling, and have a simplified syntax for this.
253
254.. _checking_facts:
255
256Gathering Facts
257```````````````
258
259Facts are described in the playbooks section and represent discovered variables about a
260system.  These can be used to implement conditional execution of tasks but also just to get ad-hoc information about your system. You can see all facts via::
261
262    $ ansible all -m setup
263
264Its also possible to filter this output to just export certain facts, see the "setup" module documentation for details.
265
266Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`Playbooks <playbooks>`. 
267
268.. seealso::
269
270   :doc:`intro_configuration`
271       All about the Ansible config file
272   :doc:`modules`
273       A list of available modules
274   :doc:`playbooks`
275       Using Ansible for configuration management & deployment
276   `Mailing List <http://groups.google.com/group/ansible-project>`_
277       Questions? Help? Ideas?  Stop by the list on Google Groups
278   `irc.freenode.net <http://irc.freenode.net>`_
279       #ansible IRC chat channel