1 files changed, 108 insertions, 0 deletions
diff --git a/tools/manpagegen/bcfg2-crypt.8.ronn b/tools/manpagegen/bcfg2-crypt.8.ronn
new file mode 100644
index 000000000..a164d47f1
--- /dev/null
+++ b/tools/manpagegen/bcfg2-crypt.8.ronn
@@ -0,0 +1,108 @@
+bcfg2-crypt(8) -- Bcfg2 encryption and decryption utility
+=========================================================
+
+## SYNOPSIS
+
+`bcfg2-crypt` [<-C configfile>] [--decrypt|--encrypt] [--cfg|--properties] [--remove] [--xpath <xpath>] [-p <passphrase-or-name>] [-v] <filename> [<filename>...]
+
+## DESCRIPTION
+
+`bcfg2-crypt` performs encryption and decryption of Cfg and Properties
+files.  It's often sufficient to run `bcfg2-crypt` with only the name
+of the file you wish to encrypt or decrypt; it can usually figure out
+what to do.
+
+## OPTIONS
+
+  * `-C` <configfile>:
+    Specify alternate bcfg2.conf location
+
+  * `--decrypt`, `--encrypt`:
+    Specify which operation you'd like to perform.  `bcfg2-crypt` can
+    usually determine which is necessary based on the contents of each
+    file.
+
+  * `--cfg`:
+    Tell `bcfg2-crypt` that an XML file should be encrypted in its
+    entirety rather than element-by-element.  This is only necessary
+    if the file is an XML file whose name ends with `.xml` and whose
+    top-level tag is `<Properties>`.  See [MODES] below for details.
+
+  * `--properties`:
+    Tell `bcfg2-crypt` to process a file as an XML Properties file,
+    and encrypt the text of each element separately.  This is
+    necessary if, for example, you've used a different top-level tag
+    than `<Properties>` in your Properties files.  See [MODES] below
+    for details.
+
+  * `--remove`:
+    Remove the plaintext file after it has been encrypted.  Only
+    meaningful for Cfg files.
+
+  * `--xpath <xpath>`:
+    Encrypt the character content of all elements that match the
+    specified XPath expression.  The default is `*[@encrypted]`
+    or `*`; see [MODES] below for more details. Only meaningful for
+    Properties files.
+
+  * `-p <passphrase>`:
+    Specify the name of a passphrase specified in the `[encryption]`
+    section of `bcfg2.conf`.  See [SELECTING PASSPHRASE] below for
+    more details.
+
+  * `-v`:
+    Be verbose.
+
+  * `-h`:
+    Display help and exit.
+
+## MODES
+
+`bcfg2-crypt` can encrypt Cfg files or Properties files; they are
+handled very differently.
+
+  * Cfg:
+    When `bcfg2-crypt` is used on a Cfg file, the entire file is
+    encrypted.  This is the default behavior on files that are not
+    XML, or that are XML but whose top-level tag is not
+    `<Properties>`.  This can be enforced by use of the `--cfg`
+    option.
+
+  * Properties:
+    When `bcfg2-crypt` is used on a Properties file, it encrypts the
+    character content of elements matching the XPath expression given
+    by `--xpath`.  By default the expression is `*[@encrypted]`, which
+    matches all elements with an `encrypted` attribute.  If you are
+    encrypting a file and that expression doesn't match any elements,
+    then the default is `*`, which matches everything.  When
+    `bcfg2-crypt` encrypts the character content of an element, it
+    also adds the `encrypted` attribute, set to the name of the
+    passphrase used to encrypt that element.  When it decrypts an
+    element it does not remove `encrypted`, though; this lets you
+    easily and efficiently run `bcfg2-crypt` against a single
+    Properties file to encrypt and decrypt it without needing to
+    specify a long list of options.  See the online Bcfg2 docs on
+    Properties files for more information on how this works.
+
+## SELECTING PASSPHRASE
+
+The passphrase used to encrypt or decrypt a file is discovered in the
+following order:
+
+  * First, the passphrase given on the command line using `-p` is
+    used.
+
+  * Next, if exactly one passphrase is specified in `bcfg2.conf`, it
+    will be used.
+
+  * Next, if operating in Properties mode, `bcfg2-crypt` will attempt
+    to read the name of the passphrase from the encrypted elements.
+
+  * Next, if decrypting, all passphrases will be tried sequentially.
+
+  * If no passphrase has been determined at this point, an error is
+    produced and the file being encrypted or decrypted is skipped.
+
+## SEE ALSO
+
+bcfg2-server(8)