1
From 12c812f030a6e5882544567990d81d0c1f882230 Mon Sep 17 00:00:00 2001
2
From: James Cammarata <jimi@sngx.net>
3
Date: Mon, 17 Mar 2014 10:00:51 -0500
4
Subject: [PATCH] Adding a man page for ansible-vault
9
docs/man/man1/ansible-vault.1 | 103 ++++++++++++++++++++++++
10
docs/man/man1/ansible-vault.1.asciidoc.in | 126 ++++++++++++++++++++++++++++++
11
3 files changed, 230 insertions(+), 1 deletion(-)
12
create mode 100644 docs/man/man1/ansible-vault.1
13
create mode 100644 docs/man/man1/ansible-vault.1.asciidoc.in
15
diff --git a/Makefile b/Makefile
16
index 41d80a1..dc2a910 100644
19
@@ -20,7 +20,7 @@ OS = $(shell uname -s)
20
# Manpages are currently built with asciidoc -- would like to move to markdown
21
# This doesn't evaluate until it's called. The -D argument is the
22
# directory of the target file ($@), kinda like `dirname`.
23
-MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1 docs/man/man1/ansible-doc.1 docs/man/man1/ansible-galaxy.1
24
+MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1 docs/man/man1/ansible-doc.1 docs/man/man1/ansible-galaxy.1 docs/man/man1/ansible-vault.1
25
ifneq ($(shell which a2x 2>/dev/null),)
26
ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $<
27
ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml
28
diff --git a/docs/man/man1/ansible-vault.1 b/docs/man/man1/ansible-vault.1
30
index 0000000..cced9f1
32
+++ b/docs/man/man1/ansible-vault.1
35
+.\" Title: ansible-vault
36
+.\" Author: [see the "AUTHOR" section]
37
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
39
+.\" Manual: System administration commands
40
+.\" Source: Ansible 1.6
41
+.\" Language: English
43
+.TH "ANSIBLE\-VAULT" "1" "03/17/2014" "Ansible 1\&.6" "System administration commands"
44
+.\" -----------------------------------------------------------------
45
+.\" * Define some portability stuff
46
+.\" -----------------------------------------------------------------
47
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48
+.\" http://bugs.debian.org/507673
49
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
50
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51
+.ie \n(.g .ds Aq \(aq
53
+.\" -----------------------------------------------------------------
54
+.\" * set default formatting
55
+.\" -----------------------------------------------------------------
56
+.\" disable hyphenation
58
+.\" disable justification (adjust text to left margin only)
60
+.\" -----------------------------------------------------------------
61
+.\" * MAIN CONTENT STARTS HERE *
62
+.\" -----------------------------------------------------------------
64
+ansible-vault \- manage encrypted YAML data\&.
67
+ansible\-vault [create|decrypt|edit|encrypt|rekey] [\-\-help] [options] file_name
70
+\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!
72
+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\&.
75
+The following options are available to all sub\-commands:
77
+\fB\-\-vault\-password\-file=\fR\fIFILE\fR
79
+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\&.
82
+\fB\-h\fR, \fB\-\-help\fR
84
+Show a help message related to the given sub\-command\&.
89
+Enable debugging output for troubleshooting\&.
93
+\fB$ ansible\-vault create [options] FILE\fR
95
+The \fBcreate\fR sub\-command is used to initialize a new encrypted file\&.
97
+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\&.
99
+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\&.
101
+The default cipher is AES (which is shared\-secret based)\&.
104
+\fB$ ansible\-vault edit [options] FILE\fR
106
+The \fBedit\fR sub\-command is used to modify a file which was previously encrypted using ansible\-vault\&.
108
+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\&.
111
+*$ ansible\-vault rekey [options] FILE_1 [FILE_2, \&..., FILE_N]
113
+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\&.
116
+*$ ansible\-vault encrypt [options] FILE_1 [FILE_2, \&..., FILE_N]
118
+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\&.
121
+*$ ansible\-vault decrypt [options] FILE_1 [FILE_2, \&..., FILE_N]
123
+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\&.
126
+Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
129
+Copyright \(co 2014, Michael DeHaan
131
+Ansible is released under the terms of the GPLv3 License\&.
134
+\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)
136
+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
137
diff --git a/docs/man/man1/ansible-vault.1.asciidoc.in b/docs/man/man1/ansible-vault.1.asciidoc.in
139
index 0000000..daccd87
141
+++ b/docs/man/man1/ansible-vault.1.asciidoc.in
146
+:man source: Ansible
147
+:man version: %VERSION%
148
+:man manual: System administration commands
152
+ansible-vault - manage encrypted YAML data.
157
+ansible-vault [create|decrypt|edit|encrypt|rekey] [--help] [options] file_name
163
+*ansible-vault* can encrypt any structured data file used by Ansible. This can include
164
+*group_vars/* or *host_vars/* inventory variables, variables loaded by *include_vars* or
165
+*vars_files*, or variable files passed on the ansible-playbook command line with
166
+*-e @file.yml* or *-e @file.json*. Role variables and defaults are also included!
168
+Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with
169
+vault. If you’d like to not betray what variables you are even using, you can go as far to
170
+keep an individual task file entirely encrypted.
176
+The following options are available to all sub-commands:
178
+*--vault-password-file=*'FILE'::
180
+A file containing the vault password to be used during the encryption/decryption
181
+steps. Be sure to keep this file secured if it is used.
185
+Show a help message related to the given sub-command.
189
+Enable debugging output for troubleshooting.
194
+*$ ansible-vault create [options] FILE*
196
+The *create* sub-command is used to initialize a new encrypted file.
198
+First you will be prompted for a password. The password used with vault currently
199
+must be the same for all files you wish to use together at the same time.
201
+After providing a password, the tool will launch whatever editor you have defined
202
+with $EDITOR, and defaults to vim. Once you are done with the editor session, the
203
+file will be saved as encrypted data.
205
+The default cipher is AES (which is shared-secret based).
210
+*$ ansible-vault edit [options] FILE*
212
+The *edit* sub-command is used to modify a file which was previously encrypted
213
+using ansible-vault.
215
+This command will decrypt the file to a temporary file and allow you to edit the
216
+file, saving it back when done and removing the temporary file.
221
+*$ ansible-vault rekey [options] FILE_1 [FILE_2, ..., FILE_N]
223
+The *rekey* command is used to change the password on a vault-encrypted files.
224
+This command can update multiple files at once, and will prompt for both the
225
+old and new passwords before modifying any data.
230
+*$ ansible-vault encrypt [options] FILE_1 [FILE_2, ..., FILE_N]
232
+The *encrypt* sub-command is used to encrypt pre-existing data files. As with the
233
+*rekey* command, you can specify multiple files in one command.
238
+*$ ansible-vault decrypt [options] FILE_1 [FILE_2, ..., FILE_N]
240
+The *decrypt* sub-command is used to remove all encryption from data files. The files
241
+will be stored as plain-text YAML once again, so be sure that you do not run this
242
+command on data files with active passwords or other sensitive data. In most cases,
243
+users will want to use the *edit* sub-command to modify the files securely.
249
+Ansible was originally written by Michael DeHaan. See the AUTHORS file
250
+for a complete list of contributors.
256
+Copyright © 2014, Michael DeHaan
258
+Ansible is released under the terms of the GPLv3 License.
264
+*ansible*(1), *ansible-pull*(1), *ansible-doc*(1)
266
+Extensive documentation is available in the documentation site:
267
+<http://docs.ansible.com>. IRC and mailing list info can be found
268
+in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>
added
removed
debian/patches/ansible-vault-manpage.patch
