aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Ryder <tom@sanctum.geek.nz>2017-10-05 19:42:50 +1300
committerTom Ryder <tom@sanctum.geek.nz>2017-10-05 19:42:50 +1300
commitaa5a3223c2b0eb295f05c6947cfdc2a254c42fa4 (patch)
treedcc1472e4b8f07f2a72dcabc643846fff4a49263
parentCorrect a couple of POD boners (diff)
downloadMail-Run-Crypt-aa5a3223c2b0eb295f05c6947cfdc2a254c42fa4.tar.gz
Mail-Run-Crypt-aa5a3223c2b0eb295f05c6947cfdc2a254c42fa4.zip
Add a README.markdown
Just pod2markdown of the module documentation
-rw-r--r--README.markdown149
1 files changed, 149 insertions, 0 deletions
diff --git a/README.markdown b/README.markdown
new file mode 100644
index 0000000..335c248
--- /dev/null
+++ b/README.markdown
@@ -0,0 +1,149 @@
+# NAME
+
+Mail::Run::Crypt - Encrypt and mail output from command runs
+
+# VERSION
+
+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 mailed (each stream 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 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 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 `croncrypt(1)` program installed by
+this distribution, which provides a means to set the properties for the module
+via environment variables or command-line options.
+
+# SYNOPSIS
+
+ my $mrc = Mail::Run::Crypt->new(
+ keyid => 0x1234DEAD,
+ passphrase => 'extremely_insecure',
+ mailto => 'you@example.net',
+ );
+ $mrc->run(qw(rsync -a /mnt/a/ remote:mnt/b));
+
+
+# SUBROUTINES/METHODS
+
+## **new(%opts)**
+
+Constructor accepts the following named parameters:
+
+- `keyid`
+
+ The GnuPG key ID that should be used to encrypt the messages.
+
+- `passphrase`
+
+ The passphrase used to decrypt the key.
+
+- `mailto`
+
+ The recipient email address for the content.
+
+- `name`
+
+ (Optional) The name of the object. When called from the `croncrypt(1)`
+ program, this will be the string "croncrypt".
+
+## **run(@command)**
+
+Run the specified arguments as a command with `IPC::Run3::run3()`, and email
+any output or error content to the email recipient.
+
+## **bail()**
+
+Return the exit status of the most recently run command, or 127 if no command
+has been successfully run.
+
+# DIAGNOSTICS
+
+- %s required
+
+ One of the required properties was not passed to the constructor.
+
+# 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.
+
+# DEPENDENCIES
+
+- Perl v5.10.0 or newer
+- `Carp`
+- `Const::Fast`
+- `English`
+- `IPC::Run3`
+- `Mail::GnuPG`
+- `MIME::Entity`
+
+# INCOMPATIBILITIES
+
+This module uses `Mail::GnuPG` and other GPG-specific code, so it won't work
+with any other OpenPGP implementations.
+
+# BUGS AND LIMITATIONS
+
+Providing the `passphrase` directly from an environment variable is not great.
+The documentation needs to make that clear and offer a less bad alternative,
+probably specifying the path to a secure file that it refuses to use unless it
+has sufficiently restrictive permissions.
+
+This is very hard to test and the author has not yet figured out how to do
+that.
+
+# AUTHOR
+
+Tom Ryder `<tom@sanctum.geek.nz>`
+
+# LICENSE AND COPYRIGHT
+
+Copyright (C) 2017 Tom Ryder
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the Artistic License (2.0). You may obtain a copy of the full
+license at:
+
+[http://www.perlfoundation.org/artistic\_license\_2\_0](http://www.perlfoundation.org/artistic_license_2_0)
+
+Any use, modification, and distribution of the Standard or Modified Versions is
+governed by this Artistic License. By using, modifying or distributing the
+Package, you accept this license. Do not use, modify, or distribute the
+Package, if you do not accept this license.
+
+If your Modified Version has been derived from a Modified Version made by
+someone other than you, you are nevertheless required to ensure that your
+Modified Version complies with the requirements of this license.
+
+This license does not grant you the right to use any trademark, service mark,
+tradename, or logo of the Copyright Holder.
+
+This license includes the non-exclusive, worldwide, free-of-charge patent
+license to make, have made, use, offer to sell, sell, import and otherwise
+transfer the Package with respect to any patent claims licensable by the
+Copyright Holder that are necessarily infringed by the Package. If you
+institute patent litigation (including a cross-claim or counterclaim) against
+any party alleging that the Package constitutes direct or contributory patent
+infringement, then this Artistic License to you shall terminate on the date
+that such litigation is filed.
+
+Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND
+CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
+NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW.
+UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY
+OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.