mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Merge pull request #167 from marktheunissen/fix_mysql_docs
Fixing the MySQL docs
This commit is contained in:
Michael DeHaan
commit
532381203e
1 changed files with 69 additions and 53 deletions
122
rst/modules.rst
122
rst/modules.rst
|
|
@ -1,11 +1,11 @@
|
|||
Ansible Modules
|
||||
===============
|
||||
|
||||
Ansible ships with a number of modules (called the 'module library')
|
||||
Ansible ships with a number of modules (called the 'module library')
|
||||
that can be executed directly on remote hosts or through :doc:`playbooks`.
|
||||
Users can also write their own modules. These modules can control system
|
||||
resources, like services, packages, or files (anything really), or
|
||||
handle executing system commands.
|
||||
resources, like services, packages, or files (anything really), or
|
||||
handle executing system commands.
|
||||
|
||||
Let's review how we execute three different modules from the command line::
|
||||
|
||||
|
|
@ -13,14 +13,14 @@ Let's review how we execute three different modules from the command line::
|
|||
ansible webservers -m ping
|
||||
ansible webservers -m command -a "/sbin/reboot -t now"
|
||||
|
||||
Each module supports taking arguments. Nearly all modules take ``key=value``
|
||||
arguments, space delimited. Some modules take no arguments, and the
|
||||
Each module supports taking arguments. Nearly all modules take ``key=value``
|
||||
arguments, space delimited. Some modules take no arguments, and the
|
||||
command/shell modules simply take the string of the command you want to run.
|
||||
|
||||
From playbooks, Ansible modules are executed in a very similar way::
|
||||
|
||||
- name: reboot the servers
|
||||
action: command /sbin/reboot -t now
|
||||
action: command /sbin/reboot -t now
|
||||
|
||||
All modules technically return JSON format data, though if you are using the
|
||||
command line or playbooks, you don't really need to know much about
|
||||
|
|
@ -45,10 +45,10 @@ Manages apt-packages (such as for Debian/Ubuntu).
|
|||
+====================+==========+=========+============================================================================+
|
||||
| name | no | | A package name or package specifier with version, like `foo` or `foo=1.0` |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| state | no | present | 'absent', 'present', or 'latest'. |
|
||||
| state | no | present | 'absent', 'present', or 'latest'. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| update_cache | no | no | Run the equivalent of apt-get update before the operation. |
|
||||
| | | | Can be run as part of the package installation or a seperate step |
|
||||
| | | | Can be run as part of the package installation or a seperate step |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| purge | no | no | Will forge purge of configuration files if state is set to 'absent'. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
|
|
@ -124,7 +124,7 @@ command
|
|||
```````
|
||||
|
||||
The command module takes the command name followed by a list of
|
||||
arguments, space delimited.
|
||||
arguments, space delimited.
|
||||
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| parameter | required | default | comments |
|
||||
|
|
@ -137,12 +137,12 @@ arguments, space delimited.
|
|||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
|
||||
The given command will be executed on all selected nodes. It will not
|
||||
be processed through the shell, so variables like "$HOME" and
|
||||
be processed through the shell, so variables like "$HOME" and
|
||||
operations like "<", ">", "|", and "&" will not work. As such, all
|
||||
paths to commands must be fully qualified.
|
||||
|
||||
NOTE:: If you want to run a command through the shell (say you are using
|
||||
'<', '>', '|', etc), you actually want the 'shell' module instead.
|
||||
'<', '>', '|', etc), you actually want the 'shell' module instead.
|
||||
The 'command' module is much more secure as it's not affected by the user's environment.
|
||||
|
||||
Example action from Ansible :doc:`playbooks`::
|
||||
|
|
@ -171,7 +171,7 @@ module.
|
|||
| src | yes | | Local path to a file to copy to the remote server, can be absolute or |
|
||||
| | | | relative. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| dest | yes | | Remote absolute path where the file should end up |
|
||||
| dest | yes | | Remote absolute path where the file should end up |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| OTHERS | | | All arguments the file module takes are also supported |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
|
|
@ -187,13 +187,13 @@ facter
|
|||
``````
|
||||
|
||||
Runs the discovery program 'facter' on the remote system, returning
|
||||
JSON data that can be useful for inventory purposes.
|
||||
JSON data that can be useful for inventory purposes.
|
||||
|
||||
Requires that 'facter' and 'ruby-json' be installed on the remote end.
|
||||
|
||||
Playbooks do not actually use this module, they use the :ref:`setup`
|
||||
module behind the scenes.
|
||||
|
||||
|
||||
Example from /usr/bin/ansible::
|
||||
|
||||
ansible foo.example.org -m ohai
|
||||
|
|
@ -254,7 +254,7 @@ support the same options as the file module -- including 'copy', 'template', and
|
|||
| src | | | path of the file to link to (applies only to state=link) |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| seuser | | | user part of SELinux file context. Will default to system policy, if |
|
||||
| | | | applicable. If set to '_default', it will use the 'user' portion of the |
|
||||
| | | | applicable. If set to '_default', it will use the 'user' portion of the |
|
||||
| | | | the policy if available |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| serole | | | role part of SELinux file context, '_default' feature works as above. |
|
||||
|
|
@ -388,28 +388,35 @@ mysql_db
|
|||
|
||||
Add or remove MySQL databases from a remote host.
|
||||
|
||||
+--------------------+----------+----------+-----------------------------------------------------------------------------+
|
||||
| parameter | required | default | comments |
|
||||
+====================+==========+==========+=============================================================================+
|
||||
| name | yes | | name of the database to add or remove |
|
||||
+--------------------+----------+-----------+----------------------------------------------------------------------------+
|
||||
| login_user | no | | user used to authenticate with |
|
||||
+--------------------+----------+-----------+----------------------------------------------------------------------------+
|
||||
| login_password | no | | password used to authenticate with |
|
||||
+--------------------+----------+-----------+----------------------------------------------------------------------------+
|
||||
| login_host | no | localhost | host running the database |
|
||||
+--------------------+----------+-----------+----------------------------------------------------------------------------+
|
||||
| state | no | present | 'absent' or 'present' |
|
||||
+--------------------+----------+-----------+----------------------------------------------------------------------------+
|
||||
| collation | no | | collation mode |
|
||||
+--------------------+----------+-----------+----------------------------------------------------------------------------+
|
||||
| encoding | no | | encoding mode |
|
||||
+--------------------+----------+-----------+----------------------------------------------------------------------------+
|
||||
Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as
|
||||
apt-get install python-mysqldb.
|
||||
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
| parameter | required | default | comments |
|
||||
+====================+==========+===========+=============================================================================+
|
||||
| name | yes | | name of the database to add or remove |
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
| login_user | no | | user name used to authenticate with |
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
| login_password | no | | password used to authenticate with |
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
| login_host | no | localhost | host running the database |
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
| state | no | present | 'absent' or 'present' |
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
| collation | no | | collation mode |
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
| encoding | no | | encoding mode |
|
||||
+--------------------+----------+-----------+-----------------------------------------------------------------------------+
|
||||
|
||||
Both 'login_password' and 'login_username' are required when you are passing credentials.
|
||||
If none are present, the module will attempt to read the credentials from ~/.my.cnf, and
|
||||
finally fall back to using the MySQL default login of 'root' with no password.
|
||||
|
||||
Example action from Ansible :doc:`playbooks`::
|
||||
|
||||
- name: Create database
|
||||
action: mysql_db loginpass=$mysql_root_password db=bobdata state=present
|
||||
action: mysql_db db=bobdata state=present
|
||||
|
||||
|
||||
mysql_user
|
||||
|
|
@ -417,33 +424,42 @@ mysql_user
|
|||
|
||||
Adds or removes a user from a MySQL database.
|
||||
|
||||
Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as
|
||||
apt-get install python-mysqldb.
|
||||
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| parameter | required | default | comments |
|
||||
+====================+==========+============+============================================================================+
|
||||
| name | yes | | name of the user (role) to add or remove |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| password | yes | | set the user's password |
|
||||
| password | no | | set the user's password |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| db | yes | | name of an existing database to grant user access to |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| login_user | no | | user (role) used to authenticate with |
|
||||
| login_user | no | | user name used to authenticate with |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| login_password | no | | password used to authenticate with |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| login_host | no | localhost | host running MySQL. Default (blank) implies localhost |
|
||||
| login_host | no | localhost | host running MySQL. |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| priv | no | | MySQL priveledges string |
|
||||
| priv | no | | MySQL privileges string in the format: db.table:priv1,priv2 |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
| state | no | present | 'absent' or 'present' |
|
||||
+--------------------+----------+------------+----------------------------------------------------------------------------+
|
||||
|
||||
Both 'login_password' and 'login_username' are required when you are passing credentials.
|
||||
If none are present, the module will attempt to read the credentials from ~/.my.cnf, and
|
||||
finally fall back to using the MySQL default login of 'root' with no password.
|
||||
|
||||
Example privileges string format:
|
||||
|
||||
mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
|
||||
|
||||
Example action from Ansible :doc:`playbooks`::
|
||||
|
||||
- name: Create database user
|
||||
action: mysql_user loginpass=$mysql_root_password name=bob passwd=12345 priv=*.*:ALL state=present
|
||||
action: mysql_user name=bob passwd=12345 priv=*.*:ALL state=present
|
||||
|
||||
- name: Ensure no user named 'sally' exists
|
||||
action: mysql_user loginpass=$mysql_root_password name=sally state=absent
|
||||
- name: Ensure no user named 'sally' exists, also passing in the auth credentials.
|
||||
action: mysql_user login_user=root login_password=123456 name=sally state=absent
|
||||
|
||||
|
||||
.. _ohai:
|
||||
|
|
@ -561,12 +577,12 @@ Executes a low-down and dirty SSH command, not going through the module subsyste
|
|||
|
||||
This is useful and should only be done in two cases. The first case is installing
|
||||
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
|
||||
to run modules, since nearly all core modules require it. Another is speaking to any
|
||||
to run modules, since nearly all core modules require it. Another is speaking to any
|
||||
devices such as routers that do not have any Python installed. In any other case,
|
||||
using the 'shell' or 'command' module is much more appropriate.
|
||||
|
||||
Arguments given to 'raw' are run directly through the configured remote shell and
|
||||
only output is returned. There is no error detection or change handler support
|
||||
Arguments given to 'raw' are run directly through the configured remote shell and
|
||||
only output is returned. There is no error detection or change handler support
|
||||
for this module.
|
||||
|
||||
Example from `/usr/bin/ansible` to bootstrap a legacy python 2.4 host::
|
||||
|
|
@ -680,7 +696,7 @@ More ansible facts will be added with successive releases.
|
|||
If facter or ohai are installed, variables from these programs will
|
||||
also be snapshotted into the JSON file for usage in templating. These
|
||||
variables are prefixed with ``facter_`` and ``ohai_`` so it's easy to
|
||||
tell their source.
|
||||
tell their source.
|
||||
|
||||
All variables are bubbled up to the caller. Using the ansible facts and choosing
|
||||
to not install facter and ohai means you can avoid ruby-dependencies
|
||||
|
|
@ -710,9 +726,9 @@ but runs the command through the user's configured shell on the remote node.
|
|||
| chdir | no | | cd into this directory before running the command (0.6 and later) |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
|
||||
The given command will be executed on all selected nodes.
|
||||
The given command will be executed on all selected nodes.
|
||||
|
||||
NOTE:: If you want to execute a command securely and predicably, it may
|
||||
NOTE:: If you want to execute a command securely and predicably, it may
|
||||
be better to use the 'command' module instead. Best practices
|
||||
when writing playbooks will follow the trend of using 'command'
|
||||
unless 'shell' is explicitly required. When running ad-hoc commands,
|
||||
|
|
@ -728,7 +744,7 @@ Example action from a playbook::
|
|||
template
|
||||
````````
|
||||
|
||||
Templates a file out to a remote server.
|
||||
Templates a file out to a remote server.
|
||||
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| parameter | required | default | comments |
|
||||
|
|
@ -766,13 +782,13 @@ Creates user accounts, manipulates existing user accounts, and removes user acco
|
|||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| groups | | | puts the user in this comma-delimited list of groups |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| append | | no | if 'yes', will only add groups, not set them to just the list in 'groups' |
|
||||
| append | | no | if 'yes', will only add groups, not set them to just the list in 'groups' |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| shell | | | optionally set the user's shell |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| createhome | | yes | unless 'no', a home directory will be made for the user |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| home | | | sets where the user's homedir should be, if not the default |
|
||||
| home | | | sets where the user's homedir should be, if not the default |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| password | | | optionally set the user's password to this crypted value. See the user's |
|
||||
| | | | example in the github examples directory for what this looks like in a |
|
||||
|
|
@ -783,7 +799,7 @@ Creates user accounts, manipulates existing user accounts, and removes user acco
|
|||
| system | | no | only when initially creating, setting this to 'yes' makes the user a |
|
||||
| | | | system account. This setting cannot be changed on existing users. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| force | | no | when used with state=absent, behavior is as with userdel --force |
|
||||
| force | | no | when used with state=absent, behavior is as with userdel --force |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| remove | | no | when used with state=remove, behavior is as with userdel --remove |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
|
|
@ -850,7 +866,7 @@ Will install, upgrade, remove, and list packages with the yum package manager.
|
|||
+====================+==========+=========+============================================================================+
|
||||
| name | yes | | package name, or package specifier with version, like 'name-1.0' |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| state | | present | 'present', 'latest', or 'absent'. |
|
||||
| state | | present | 'present', 'latest', or 'absent'. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| list | | | various non-idempotent commands for usage with /usr/bin/ansible and not |
|
||||
| | | | playbooks. See examples below. |
|
||||
|
|
|
|||
Loading…
Reference in a new issue