From aa5a3223c2b0eb295f05c6947cfdc2a254c42fa4 Mon Sep 17 00:00:00 2001 From: Tom Ryder Date: Thu, 5 Oct 2017 19:42:50 +1300 Subject: Add a README.markdown Just pod2markdown of the module documentation --- README.markdown | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 README.markdown 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 `` + +# 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. -- cgit v1.2.3