Adding a man page for ansible-vault

Fixes #6471

2 files changed, 229 insertions, 0 deletions

diff --git a/docs/man/man1/ansible-vault.1 b/docs/man/man1/ansible-vault.1
new file mode 100644
index 0000000000..cced9f1bcf
--- /dev/null
+++ b/docs/man/man1/ansible-vault.1
@@ -0,0 +1,103 @@
+'\" t
+.\"     Title: ansible-vault
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 03/17/2014
+.\"    Manual: System administration commands
+.\"    Source: Ansible 1.6
+.\"  Language: English
+.\"
+.TH "ANSIBLE\-VAULT" "1" "03/17/2014" "Ansible 1\&.6" "System administration commands"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+ansible-vault \- manage encrypted YAML data\&.
+.SH "SYNOPSIS"
+.sp
+ansible\-vault [create|decrypt|edit|encrypt|rekey] [\-\-help] [options] file_name
+.SH "DESCRIPTION"
+.sp
+\fBansible\-vault\fR can encrypt any structured data file used by Ansible\&. This can include \fBgroup_vars/\fR or \fBhost_vars/\fR inventory variables, variables loaded by \fBinclude_vars\fR or \fBvars_files\fR, or variable files passed on the ansible\-playbook command line with \fB\-e @file\&.yml\fR or \fB\-e @file\&.json\fR\&. Role variables and defaults are also included!
+.sp
+Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault\&. If you\(cqd like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted\&.
+.SH "COMMON OPTIONS"
+.sp
+The following options are available to all sub\-commands:
+.PP
+\fB\-\-vault\-password\-file=\fR\fIFILE\fR
+.RS 4
+A file containing the vault password to be used during the encryption/decryption steps\&. Be sure to keep this file secured if it is used\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Show a help message related to the given sub\-command\&.
+.RE
+.PP
+\fB\-\-debug\fR
+.RS 4
+Enable debugging output for troubleshooting\&.
+.RE
+.SH "CREATE"
+.sp
+\fB$ ansible\-vault create [options] FILE\fR
+.sp
+The \fBcreate\fR sub\-command is used to initialize a new encrypted file\&.
+.sp
+First you will be prompted for a password\&. The password used with vault currently must be the same for all files you wish to use together at the same time\&.
+.sp
+After providing a password, the tool will launch whatever editor you have defined with $EDITOR, and defaults to vim\&. Once you are done with the editor session, the file will be saved as encrypted data\&.
+.sp
+The default cipher is AES (which is shared\-secret based)\&.
+.SH "EDIT"
+.sp
+\fB$ ansible\-vault edit [options] FILE\fR
+.sp
+The \fBedit\fR sub\-command is used to modify a file which was previously encrypted using ansible\-vault\&.
+.sp
+This command will decrypt the file to a temporary file and allow you to edit the file, saving it back when done and removing the temporary file\&.
+.SH "REKEY"
+.sp
+*$ ansible\-vault rekey [options] FILE_1 [FILE_2, \&..., FILE_N]
+.sp
+The \fBrekey\fR command is used to change the password on a vault\-encrypted files\&. This command can update multiple files at once, and will prompt for both the old and new passwords before modifying any data\&.
+.SH "ENCRYPT"
+.sp
+*$ ansible\-vault encrypt [options] FILE_1 [FILE_2, \&..., FILE_N]
+.sp
+The \fBencrypt\fR sub\-command is used to encrypt pre\-existing data files\&. As with the \fBrekey\fR command, you can specify multiple files in one command\&.
+.SH "DECRYPT"
+.sp
+*$ ansible\-vault decrypt [options] FILE_1 [FILE_2, \&..., FILE_N]
+.sp
+The \fBdecrypt\fR sub\-command is used to remove all encryption from data files\&. The files will be stored as plain\-text YAML once again, so be sure that you do not run this command on data files with active passwords or other sensitive data\&. In most cases, users will want to use the \fBedit\fR sub\-command to modify the files securely\&.
+.SH "AUTHOR"
+.sp
+Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
+.SH "COPYRIGHT"
+.sp
+Copyright \(co 2014, Michael DeHaan
+.sp
+Ansible is released under the terms of the GPLv3 License\&.
+.SH "SEE ALSO"
+.sp
+\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)
+.sp
+Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible
diff --git a/docs/man/man1/ansible-vault.1.asciidoc.in b/docs/man/man1/ansible-vault.1.asciidoc.in
new file mode 100644
index 0000000000..daccd8772f
--- /dev/null
+++ b/docs/man/man1/ansible-vault.1.asciidoc.in
@@ -0,0 +1,126 @@
+ansible-vault(1)
+================
+:doctype:      manpage
+:man source:   Ansible
+:man version:  %VERSION%
+:man manual:   System administration commands
+
+NAME
+----
+ansible-vault - manage encrypted YAML data.
+
+
+SYNOPSIS
+--------
+ansible-vault [create|decrypt|edit|encrypt|rekey] [--help] [options] file_name
+
+
+DESCRIPTION
+-----------
+
+*ansible-vault* can encrypt any structured data file used by Ansible. This can include 
+*group_vars/* or *host_vars/* inventory variables, variables loaded by *include_vars* or 
+*vars_files*, or variable files passed on the ansible-playbook command line with 
+*-e @file.yml* or *-e @file.json*. Role variables and defaults are also included!
+
+Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with 
+vault. If you’d like to not betray what variables you are even using, you can go as far to 
+keep an individual task file entirely encrypted.
+
+
+COMMON OPTIONS
+--------------
+
+The following options are available to all sub-commands:
+
+*--vault-password-file=*'FILE'::
+
+A file containing the vault password to be used during the encryption/decryption
+steps. Be sure to keep this file secured if it is used.
+
+*-h*, *--help*::
+
+Show a help message related to the given sub-command.
+
+*--debug*::
+
+Enable debugging output for troubleshooting.
+
+CREATE
+------
+
+*$ ansible-vault create [options] FILE*
+
+The *create* sub-command is used to initialize a new encrypted file. 
+
+First you will be prompted for a password. The password used with vault currently 
+must be the same for all files you wish to use together at the same time.
+
+After providing a password, the tool will launch whatever editor you have defined 
+with $EDITOR, and defaults to vim. Once you are done with the editor session, the 
+file will be saved as encrypted data.
+
+The default cipher is AES (which is shared-secret based).
+
+EDIT
+----
+
+*$ ansible-vault edit [options] FILE*
+
+The *edit* sub-command is used to modify a file which was previously encrypted
+using ansible-vault.
+
+This command will decrypt the file to a temporary file and allow you to edit the 
+file, saving it back when done and removing the temporary file.
+
+REKEY
+-----
+
+*$ ansible-vault rekey [options] FILE_1 [FILE_2, ..., FILE_N]
+
+The *rekey* command is used to change the password on a vault-encrypted files.
+This command can update multiple files at once, and will prompt for both the
+old and new passwords before modifying any data.
+
+ENCRYPT
+-------
+
+*$ ansible-vault encrypt [options] FILE_1 [FILE_2, ..., FILE_N]
+
+The *encrypt* sub-command is used to encrypt pre-existing data files. As with the
+*rekey* command, you can specify multiple files in one command.
+
+DECRYPT
+-------
+
+*$ ansible-vault decrypt [options] FILE_1 [FILE_2, ..., FILE_N]
+
+The *decrypt* sub-command is used to remove all encryption from data files. The files
+will be stored as plain-text YAML once again, so be sure that you do not run this
+command on data files with active passwords or other sensitive data. In most cases, 
+users will want to use the *edit* sub-command to modify the files securely.
+
+
+AUTHOR
+------
+
+Ansible was originally written by Michael DeHaan. See the AUTHORS file
+for a complete list of contributors.
+
+
+COPYRIGHT
+---------
+
+Copyright © 2014, Michael DeHaan
+
+Ansible is released under the terms of the GPLv3 License.
+
+
+SEE ALSO
+--------
+
+*ansible*(1), *ansible-pull*(1), *ansible-doc*(1)
+
+Extensive documentation is available in the documentation site:
+<http://docs.ansible.com>. IRC and mailing list info can be found
+in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>