mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
144 lines
6.8 KiB
ReStructuredText
144 lines
6.8 KiB
ReStructuredText
13 years ago
|
Getting Started
|
||
|
===============
|
||
13 years ago
|
|
||
12 years ago
|
.. contents::
|
||
|
:depth: 2
|
||
|
|
||
11 years ago
|
.. _gs_about:
|
||
|
|
||
11 years ago
|
About
|
||
|
`````
|
||
13 years ago
|
|
||
11 years ago
|
Now that you've read :doc:`intro_installation` and installed Ansible, it's time to dig in and get
|
||
11 years ago
|
started with some commands.
|
||
13 years ago
|
|
||
11 years ago
|
What we are showing first are not the powerful configuration/deployment/orchestration of Ansible, called playbooks.
|
||
11 years ago
|
Playbooks are covered in a separate section.
|
||
11 years ago
|
|
||
11 years ago
|
This section is about how to get going initially. Once you have these concepts down, read :doc:`intro_adhoc` for some more
|
||
|
detail, and then you'll be ready to dive into playbooks and explore the most interesting parts!
|
||
11 years ago
|
|
||
11 years ago
|
.. _remote_connection_information:
|
||
|
|
||
11 years ago
|
Remote Connection Information
|
||
|
`````````````````````````````
|
||
13 years ago
|
|
||
11 years ago
|
Before we get started, it's important to understand how Ansible is communicating with remote
|
||
|
machines over SSH.
|
||
13 years ago
|
|
||
11 years ago
|
By default, Ansible 1.3 and later will try to use native
|
||
11 years ago
|
OpenSSH for remote communication when possible. This enables both ControlPersist (a performance feature), Kerberos, and options in ~/.ssh/config such as Jump Host setup. When using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), however, the version of OpenSSH may be too old to support Control Persist. On these operating systems, Ansible will fallback into using a high-quality python implementation of
|
||
|
OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform -- or engage 'accelerated mode' in Ansible. See :doc:`playbooks_acceleration`.
|
||
13 years ago
|
|
||
11 years ago
|
In Ansible 1.2 and before, the default was strictly paramiko and native SSH had to be explicitly selected with -c ssh or set in the configuration file.
|
||
12 years ago
|
|
||
11 years ago
|
Occasionally you'll encounter a device that doesn't do SFTP. This is rare, but if talking with some remote devices that don't support SFTP, you can switch to SCP mode in :doc:`intro_configuration`.
|
||
13 years ago
|
|
||
11 years ago
|
When speaking with remote machines, Ansible will by default assume you are using SSH keys -- which we encourage -- but passwords are fine too. To enable password auth, supply the option --ask-pass where needed. If using sudo features and when sudo requires a password, also supply --ask-sudo-pass as appropriate.
|
||
12 years ago
|
|
||
11 years ago
|
While it may be common sense, it is worth sharing: Any management system benefits from being run near your machines you are being managed. If running in a cloud, consider running Ansible from a machine inside that cloud. It will work better than on the open
|
||
|
intranet in most cases.
|
||
13 years ago
|
|
||
11 years ago
|
As an advanced topic, Ansible doesn't just have to connect remotely over SSH. The transports are pluggable, and there are options for managing things locally, as well as managing chroot, lxc, and jail containers. A mode called 'ansible-pull' can also invert the system and have systems 'phone home' via scheduled git checkouts to pull configuration directives from a central repository.
|
||
12 years ago
|
|
||
11 years ago
|
.. _your_first_commands:
|
||
|
|
||
13 years ago
|
Your first commands
|
||
|
```````````````````
|
||
|
|
||
11 years ago
|
Now that you've installed Ansible, it's time to get started with some basics.
|
||
13 years ago
|
|
||
13 years ago
|
Edit (or create) /etc/ansible/hosts and put one or more remote systems in it, for
|
||
13 years ago
|
which you have your SSH key in ``authorized_keys``::
|
||
13 years ago
|
|
||
|
192.168.1.50
|
||
|
aserver.example.org
|
||
|
bserver.example.org
|
||
|
|
||
11 years ago
|
This is an inventory file, which is also explained in greater depth here: :doc:`intro_inventory`.
|
||
11 years ago
|
|
||
11 years ago
|
We'll assume you are using SSH keys for authentication. To set up SSH agent to avoid retyping passwords, you can
|
||
11 years ago
|
do:
|
||
13 years ago
|
|
||
12 years ago
|
.. code-block:: bash
|
||
|
|
||
|
$ ssh-agent bash
|
||
|
$ ssh-add ~/.ssh/id_rsa
|
||
13 years ago
|
|
||
12 years ago
|
(Depending on your setup, you may wish to ansible's --private-key option to specify a pem file instead)
|
||
13 years ago
|
|
||
12 years ago
|
Now ping all your nodes:
|
||
13 years ago
|
|
||
12 years ago
|
.. code-block:: bash
|
||
13 years ago
|
|
||
12 years ago
|
$ ansible all -m ping
|
||
13 years ago
|
|
||
12 years ago
|
Ansible will attempt to remote connect to the machines using your current
|
||
|
user name, just like SSH would. To override the remote user name, just use the '-u' parameter.
|
||
12 years ago
|
|
||
|
If you would like to access sudo mode, there are also flags to do that:
|
||
13 years ago
|
|
||
12 years ago
|
.. code-block:: bash
|
||
|
|
||
|
# as bruce
|
||
|
$ ansible all -m ping -u bruce
|
||
13 years ago
|
# as bruce, sudoing to root
|
||
12 years ago
|
$ ansible all -m ping -u bruce --sudo
|
||
13 years ago
|
# as bruce, sudoing to batman
|
||
12 years ago
|
$ ansible all -m ping -u bruce --sudo --sudo-user batman
|
||
13 years ago
|
|
||
11 years ago
|
(The sudo implementation is changeable in Ansible's configuration file if you happen to want to use a sudo
|
||
11 years ago
|
replacement. Flags passed to sudo (like -H) can also be set there.)
|
||
12 years ago
|
|
||
12 years ago
|
Now run a live command on all of your nodes:
|
||
13 years ago
|
|
||
12 years ago
|
.. code-block:: bash
|
||
|
|
||
|
$ ansible all -a "/bin/echo hello"
|
||
13 years ago
|
|
||
13 years ago
|
Congratulations. You've just contacted your nodes with Ansible. It's
|
||
11 years ago
|
soon going to be time to read some of the more real-world :doc:`intro_adhoc`, and explore
|
||
13 years ago
|
what you can do with different modules, as well as the Ansible
|
||
13 years ago
|
:doc:`playbooks` language. Ansible is not just about running commands, it
|
||
|
also has powerful configuration management and deployment features. There's more to
|
||
|
explore, but you already have a fully working infrastructure!
|
||
13 years ago
|
|
||
11 years ago
|
.. _a_note_about_host_key_checking:
|
||
|
|
||
11 years ago
|
Host Key Checking
|
||
|
`````````````````
|
||
12 years ago
|
|
||
|
Ansible 1.2.1 and later have host key checking enabled by default.
|
||
|
|
||
11 years ago
|
If a host is reinstalled and has a different key in 'known_hosts', this will result in a error message until corrected. If a host is not initially in 'known_hosts' this will result in prompting for confirmation of the key, which results in a interactive experience if using Ansible, from say, cron. You might not want this.
|
||
12 years ago
|
|
||
|
If you wish to disable this behavior and understand the implications, you can do so by editing /etc/ansible/ansible.cfg or ~/.ansible.cfg::
|
||
|
|
||
12 years ago
|
[defaults]
|
||
12 years ago
|
host_key_checking = False
|
||
|
|
||
12 years ago
|
Alternatively this can be set by an environment variable:
|
||
|
|
||
|
$ export ANSIBLE_HOST_KEY_CHECKING=False
|
||
|
|
||
11 years ago
|
Also note that host key checking in paramiko mode is reasonably slow, therefore switching to 'ssh' is also recommended when using this feature.
|
||
13 years ago
|
|
||
11 years ago
|
.. _a_note_about_logging:
|
||
|
|
||
|
Ansible will log some information about module arguments on the remote system in the remote syslog. To enable basic
|
||
|
logging on the control machine see `intro_config` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in `AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx>`_. AWX provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API.
|
||
|
|
||
13 years ago
|
.. seealso::
|
||
|
|
||
11 years ago
|
:doc:`intro_inventory`
|
||
|
More information about inventory
|
||
11 years ago
|
:doc:`intro_adhoc`
|
||
13 years ago
|
Examples of basic commands
|
||
|
:doc:`playbooks`
|
||
11 years ago
|
Learning Ansible's configuration management language
|
||
13 years ago
|
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||
|
Questions? Help? Ideas? Stop by the list on Google Groups
|
||
|
`irc.freenode.net <http://irc.freenode.net>`_
|
||
|
#ansible IRC chat channel
|
||
13 years ago
|
|