Metadata-Version: 1.1
Name: blackhole
Version: 1.4.2
Summary: Tornado powered MTA for accepting all incoming emails without any disk I/O, although no messages actually ever get delivered. Mainly for testing huge send rates, for making sure developers don't accidentally send emails to real users, email integration testing and things like that.
Home-page: http://blackhole.io/
Author: Kura
Author-email: kura@kura.io
License: (The MIT License)

Copyright (c) 2013 Kura

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the 'Software'), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Description: =========
        Blackhole
        =========
        
        Tornado powered MTA for accepting all incoming emails 
        without any disk I/O, although no messages actually ever 
        get delivered. 
        Mainly for testing huge send rates, for making sure developers
        don't accidentally send emails to real users, email
        integration testing and things like that.
        
        
        Requirements
        ------------
        
        * tornado 2.3
        * setproctitle 1.1.6
        
        
        Installation
        ------------
        
        Packaged
        ~~~~~~~~
        
        From PyPI
        
          pip install blackhole
        
        Or
        
          easy_install blackhole
        
        From GitHub
        ~~~~~~~~~~~
        
          pip install -e git+git://github.com/kura/blackhole.git#egg=blackhole
        
        From source
        ~~~~~~~~~~~
        
        Download the latest tarball from PyPI or GitHub. Unpack and run:
        
          python setup.py install
        
        
        Configuration
        -------------
        
        Configuration options can be passed via the command line
        as below:
        
          --host=IP					IP address to bind go [default: 0.0.0.0]
          --port=PORT				Port to listen for connections on [default: 25]
          --pid=FILE				File to write process information to [default: /tmp/blackhole.pid]
          --log=FILE				File to write logs to (not very verbose) [default: /tmp/blackhole.log]
          --user=USER				User to drop privs to during run time. [default: blackhole]
          --group=GROUP			Group to drop privs to during run time. [default: blackhole]
          --mode=MODE				Mode to run blackhole in (accept, bounce, random, unavailable, offline) [default: accept] - see MODES section
        
        SSL options
        
          --ssl=BOOL										Enabled or disable SSL, requires SSL compiled in to Python and OpenSSL. True or False [default: True]
          --ssl_port=PORT								Port to listen for SSL enabled connections [default: 465]
          --ssl_key=PATH								X509 SSL keyfile
          --ssl_cert=PATH								X509 SSL certificate file
          --ssl_ca_certs_dir=PATH				Path to your operating system's repository of certificates authorities [default: /etc/ssl/certs]
        
        
        You can also specify the `--conf` option to load configuration
        from a file:
        
          --conf=FILE		Config file to parse and use. Overrides command line args
        
        The configuration file has the following format::
        
          host="0.0.0.0"
          port=25
          pid="/tmp/blackhole.io"
          mode="offline"
          ssl_key=/etc/ssl/private/blackhole.io.key
          ssl_cert=/etc/ssl/certs/blackhole.io.crt
        
        You can find an example configuration file `example.conf-dist` in the root folder of this project.
        
        
        Usage
        -----
        
        Using the blackhole binary
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        The following commands are for use when using blackhole without an init script.
        
        +-------------------+----------------------------------------------------------+
        | blackhole start   | Starts the server                                        |
        +-------------------+----------------------------------------------------------+
        | blackhole stop    | Stops the server                                         |
        +-------------------+----------------------------------------------------------+
        | blackhole restart | Restarts the server                                      |
        +-------------------+----------------------------------------------------------+
        | blackhole status  | Shows the status of the server, running, not running etc |
        +-------------------+----------------------------------------------------------+
        
        Using init.d
        ~~~~~~~~~~~~
        
        Please see the section below on installing the init.d/rc.d script.
        
        +-------------------------------+----------------------------------------------------------+
        | /etc/init.d/blackhole start   | Starts the server                                        |
        +-------------------------------+----------------------------------------------------------+
        | /etc/init.d/blackhole stop    | Stops the server                                         |
        +-------------------------------+----------------------------------------------------------+
        | /etc/init.d/blackhole restart | Restarts the server                                      |
        +-------------------------------+----------------------------------------------------------+
        | /etc/init.d/blackhole status  | Shows the status of the server, running, not running etc |
        +-------------------------------+----------------------------------------------------------+
        
        Modes
        -----
        
        See the `Response codes` section for more information on responses
        and which mode responds with which codes.
        
        accept
        ~~~~~~
        
        Accept all email with code 250, 251, 252 or 253.
        
        bounce
        ~~~~~~
        
        Bounce all email with a random code, excluding 250, 251, 252, 253.
        
        random
        ~~~~~~
        
        Randomly accept or bounce all email with a random code.
        
        unavailable
        ~~~~~~~~~~~
        
        Server always respondes with code 421 - service is unavailable.
        
        offline
        ~~~~~~~
        
        
        Server always responds with code 521 - server does not accept mail.
        
        rc.d
        ----
        
        The init script depends on */etc/blackhole.conf* being in place and configured, see README
        section on configuration.
        
        Blackhole comes with a script that works with init.d/rc.d, to install it copy it
        from the *init.d/YOUR_DISTRO* folder in the root directory of this project to */etc/init.d/*.
        
        i.e. for Debian/Ubuntu users, mv the file from *init.d/debian-ubuntu/* to */etc/init.d/*.
        
        Then make sure it's executable::
        
          chmod +x /etc/init.d/blackhole
        
        To make blackhole start on a reboot use the following::
        
          update-rc.d blackhole defaults
        
        
        Response codes
        --------------
        
        All
        ~~~
        
        +------+------------------------------------------------------------+
        | Code | message                                                    |
        +======+============================================================+
        | 220  | OK, ready                                                  |
        +------+------------------------------------------------------------+
        | 221  | Thank you for speaking to me                               |
        +------+------------------------------------------------------------+
        | 250  | OK, done                                                   |
        +------+------------------------------------------------------------+
        | 251  | OK, user not local, will forward                           |
        +------+------------------------------------------------------------+
        | 252  | OK, cannot VRFY user but will attempt delivery             |
        +------+------------------------------------------------------------+
        | 253  | OK, messages pending                                       |
        +------+------------------------------------------------------------+
        | 354  | Start mail input; end with <CRLF>.<CRLF>                   |
        +------+------------------------------------------------------------+
        | 355  | Octet-offset is the transaction offset                     |
        +------+------------------------------------------------------------+
        | 421  | Service not available, closing transmission channel        |
        +------+------------------------------------------------------------+
        | 450  | Requested mail action not taken: mailbox unavailable       |
        +------+------------------------------------------------------------+
        | 451  | Requested action aborted: local error in processing        |
        +------+------------------------------------------------------------+
        | 452  | Requested action not taken: insufficient system storage    |
        +------+------------------------------------------------------------+
        | 454  | TLS not available due to temporary reason                  |
        +------+------------------------------------------------------------+
        | 458  | Unable to queue message                                    |
        +------+------------------------------------------------------------+
        | 459  | Not allowed: unknown reason                                |
        +------+------------------------------------------------------------+
        | 500  | Command not recognized                                     |
        +------+------------------------------------------------------------+
        | 501  | Syntax error, no parameters allowed                        |
        +------+------------------------------------------------------------+
        | 502  | Command not implemented                                    |
        +------+------------------------------------------------------------+
        | 503  | Bad sequence of commands                                   |
        +------+------------------------------------------------------------+
        | 504  | Command parameter not implemented                          |
        +------+------------------------------------------------------------+
        | 521  | Machine does not accept mail                               |
        +------+------------------------------------------------------------+
        | 530  | Must issue a STARTTLS command first                        |
        +------+------------------------------------------------------------+
        | 534  | Authentication mechanism is too weak                       |
        +------+------------------------------------------------------------+
        | 538  | Encryption required for requested authentication mechanism |
        +------+------------------------------------------------------------+
        | 550  | Requested action not taken: mailbox unavailable            |
        +------+------------------------------------------------------------+
        | 551  | User not local                                             |
        +------+------------------------------------------------------------+
        | 552  | Requested mail action aborted: exceeded storage allocation |
        +------+------------------------------------------------------------+
        | 553  | Requested action not taken: mailbox name not allowed       |
        +------+------------------------------------------------------------+
        | 554  | Transaction failed                                         |
        +------+------------------------------------------------------------+
        | 571  | Blocked                                                    |
        +------+------------------------------------------------------------+
        
        Accept
        ~~~~~~
        
        This mode will respond with the following codes:
        
        +-------------------------+
        | Codes                   |
        +=======+=====+=====+=====+
        | 250   | 251 | 252 | 253 |
        +-------+-----+-----+-----+
        
        Bounce
        ~~~~~~
        
        This mode will respond with the following codes:
        
        +-------------------------------------------------+
        | Codes                                           |
        +=======+=====+=====+=====+=====+=====+=====+=====+
        | 421   | 431 | 450 | 451 | 452 | 454 | 458 | 459 |
        +-------+-----+-----+-----+-----+-----+-----+-----+
        | 521   | 534 | 550 | 551 | 552 | 553 | 554 | 571 |
        +-------+-----+-----+-----+-----+-----+-----+-----+
        
        Offline
        ~~~~~~~
        
        This mode will respond with the following codes:
        
        +-------+
        | Codes |
        +=======+
        | 521   |
        +-------+
        
        Unavailable
        ~~~~~~~~~~~
        
        This mode will respond with the following codes:
        
        +-------+
        | Codes |
        +=======+
        | 421   |
        +-------+
        
Platform: linux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Topic :: Internet
Classifier: Topic :: Utilities
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Communications :: Email :: Mail Transport Agents
Classifier: Topic :: Communications :: Email :: Post-Office
