diff options
Diffstat (limited to 'tools/manpagegen/bcfg2-crypt.8.ronn')
-rw-r--r-- | tools/manpagegen/bcfg2-crypt.8.ronn | 108 |
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) |