aboutsummaryrefslogtreecommitdiff
path: root/README.markdown
diff options
context:
space:
mode:
authorTom Ryder <tom@sanctum.geek.nz>2017-10-14 12:02:15 +1300
committerTom Ryder <tom@sanctum.geek.nz>2017-10-14 12:11:13 +1300
commit5f2beb6dfccc4b7b1ac4fba719bf008f6ab02773 (patch)
treea8058658713ccafed2cf7146734800eaf9b128d0 /README.markdown
parentFix typo (diff)
downloadMail-Run-Crypt-5f2beb6dfccc4b7b1ac4fba719bf008f6ab02773.tar.gz
Mail-Run-Crypt-5f2beb6dfccc4b7b1ac4fba719bf008f6ab02773.zip
Fix lots of documentation and formatting
Diffstat (limited to 'README.markdown')
-rw-r--r--README.markdown105
1 files changed, 60 insertions, 45 deletions
diff --git a/README.markdown b/README.markdown
index 5327928..6e6515e 100644
--- a/README.markdown
+++ b/README.markdown
@@ -8,21 +8,22 @@ Version 0.01
# DESCRIPTION
-This module runs commands with `IPC::Run3::run3()`, and collects any standard
-output and standard error it emits. If there is any standard output or standard
-error content, it is signed and/or encrypted with GnuPG, and then mailed to a
-specified recipient address (each stream separately).
+This module runs a system command with [IPC::Run3](https://metacpan.org/pod/IPC::Run3), and collects any
+standard output and standard error it emits. If there is any standard output or
+standard error content, it is encrypted and optionally signed with GnuPG, and
+then each stream's content is mailed separately to a specified recipient
+address.
The idea is to allow you to view the output of automated commands while having
-the content encrypted as it passes through to your mailserver, and (optionally)
-have some assurance that the content was actually generated by the server
-concerned. `cron(8)` scripts are the ideal use case, but this would also work
-with `at(1)` or anything else that might non-interactively run jobs for which
+the content encrypted as it passes through to your mailserver, and optionally
+to have some assurance that the content was actually generated by the server
+concerned. **cron(8)** scripts are the ideal use case, but this would also work
+with **at(1)**, or anything else that might non-interactively run jobs for which
output is significant.
-You probably want to call this with the `runcrypt(1)` program installed by
-this distribution, which provides a means to set the properties for the module
-via environment variables or command-line options.
+You will probably want to call this with the [**runcrypt(1)**](https://metacpan.org/pod/runcrypt) program
+provided by this distribution, which includes a means to set the properties for
+the module via environment variables or command line options.
# SYNOPSIS
@@ -35,7 +36,7 @@ via environment variables or command-line options.
...
my $mrc = Mail::Run::Crypt->new(
sign => 1,
- keyid => 0x1234DEAD,
+ keyid => '0x1234DEAD5678BEEF',
passphrase => 'able was i ere i saw elba',
mailto => 'you@example.net',
);
@@ -44,85 +45,99 @@ via environment variables or command-line options.
# SUBROUTINES/METHODS
-## **new(%opts)**
+## `new(%opts)`
-Constructor accepts the following named parameters:
+Constructor method; accepts the following named parameters:
+
+- `mailto`
+
+ The recipient email address for the content. This is always required.
- `sign`
- Whether to sign the command output. This defaults to off. A key ID and
- passphrase will be required for signing.
+ Whether to sign the command output. This defaults to 0. A `keyid` and
+ `passphrase` will be required for signing.
- `encrypt`
- Whether to encrypt the command output. This defaults to on.
+ Whether to encrypt the command output. This defaults to 1.
- `keyid`
- The GnuPG key ID that should be used to encrypt the messages.
+ The GnuPG key ID that should be used to encrypt the messages. This is required
+ for signing. It can be any means of identifying the key acceptable to GnuPG;
+ the key's 16-byte ("long") hexadecimal ID prefixed with `0x` is probably the
+ best way.
- `passphrase`
- The passphrase used to decrypt the key.
-
-- `mailto`
-
- The recipient email address for the content.
+ The passphrase used to decrypt the key. This is required for signing.
- `name`
- (Optional) The name of the object. When called from the `runcrypt(1)`
- program, this will be the string "runcrypt".
+ (Optional) The name of the object. When called from the
+ [**runcrypt(1)**](https://metacpan.org/pod/runcrypt) program, this will be the string "runcrypt".
+ Otherwise, it will default to this package's name.
-## **run(@command)**
+## `run(@command)`
-Run the specified arguments as a command with `IPC::Run3::run3()`, and email
-any output or error content to the email recipient.
+Run the specified arguments as a command with [IPC::Run3](https://metacpan.org/pod/IPC::Run3), and email
+any output or error content to the email recipient, encrypting and/or signing
+as configured. Returns 1 if the command succeeded, 0 otherwise. Use
+[`bail()`](#bail) to get the actual exit code if needed.
-## **bail()**
+## `bail()`
Return the exit status of the most recently run command, or 127 if no command
has been successfully run.
# DIAGNOSTICS
-- mailto required
+- `mailto required`
The required `mailto` property was not passed in the constructor.
-- keyid required for signing
+- `keyid required for signing`
Signing was specified, but no `keyid` attribute was passed in the constructor.
-- passphrase required for signing
+- `passphrase required for signing`
Signing was specified, but no `passphrase` attribute was passed in the constructor.
-- command failed: %s
+- `command failed: %s`
- The command did not merely fail, it could not even be started, with the given
- error string. This is typically due to problems finding the executable.
+ The command could not be run at all, raising the given error string. This is
+ typically due to problems finding the executable.
# CONFIGURATION AND ENVIRONMENT
You will need to have a functioning GnuPG public key setup for this to work,
-including the secret key. You should definitely not use your personal key;
-generate one specifically for mail signing and encryption instead.
+including stored keys or a key retrieval system for your recipients. You will
+also need a secret key if you want to sign the messages.
+
+You should _definitely not_ use your personal key for this; generate one
+specifically for mail signing and encryption instead.
+
+I wrote a tutorial on GnuPG key setup, including agent configuration, as part
+of this series:
+
+[https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/](https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/)
# DEPENDENCIES
- Perl v5.10.0 or newer
-- `Carp`
-- `Const::Fast`
-- `English`
-- `IPC::Run3`
-- `Mail::GnuPG`
-- `MIME::Entity`
+- [Carp](https://metacpan.org/pod/Carp)
+- [Const::Fast](https://metacpan.org/pod/Const::Fast)
+- [English](https://metacpan.org/pod/English)
+- [IPC::Run3](https://metacpan.org/pod/IPC::Run3)
+- [Mail::GnuPG](https://metacpan.org/pod/Mail::GnuPG)
+- [MIME::Entity](https://metacpan.org/pod/MIME::Entity)
# INCOMPATIBILITIES
-This module uses `Mail::GnuPG` and other GPG-specific code, so it won't work
-with any other OpenPGP implementations.
+This module uses [Mail::GnuPG](https://metacpan.org/pod/Mail::GnuPG) and other GnuPG-specific code, so
+it won't work with other OpenPGP implementations.
# BUGS AND LIMITATIONS