_      _                          
 _ __ ___   __ _  __ _(_) ___| |__   ___  __ _ _ __ ___  
| '_ ` _ \ / _` |/ _` | |/ __| '_ \ / _ \/ _` | '_ ` _ \ 
| | | | | | (_| | (_| | | (__| |_) |  __/ (_| | | | | | |
|_| |_| |_|\__,_|\__, |_|\___|_.__/ \___|\__,_|_| |_| |_|
                 |___/

Magicbeam contains three components which I have found useful when developing fabulously robust Erlang/OTP systems.

• hotbeam handles the reloading of binary modules. optionally extracts source file location and monitors for changes in order to recompile and reload resulting beam
• thunderbeam will kill off random processes under the guises of testing supervisory structures
• shellbeam provides a simple OTP behaviour allowing one to easily define bespoke REPL shells for runtime diagnostics

In addition, magicbeam will (optionally) attempt to start a ssh server. This server will only make use of public keys. No plans to support user/password based authentication. Upon succesful connection a shellbeam REPL shellw ill be spawned.

Magicbeam can be installed either as a standalone escript or included as part of a standard OTP release as a typical rebar dependency. Building magicbeam itself will produce an includable OTP application and the escript.

Running magicbeam with no arguments will show the options. These should be fairly self-explanatory. General procedure is to specify node and cookie with load / unload to start / stop the magicbeam application. Note that this will inject the application into an already running OTP system.

Include the magicbeam repository in your rebar-enabled project. It will be started by the boot scripts when you start your node.

Magicbeam defaults to making use of OTP Application Environment for it's configuration. If you wish to be fancy many options also support any configuration system you can throw at it via a hook module which implements a simple behavior. If you are not using a hook module and have not setup the application environment you may simply make use of application:set_env/3 and magicbeam:rehash/0 to effect runtime changes.

Note that all these configuration options are in the magicbeam application.

For thunderbeam, the configuration is interpreted as follows

• processes are killed based on the rough formula of thunderbeam_wait_base * random:uniform(thunderbeam_wait_variable)
• if a process has a registered name in thunderbeam_immune_proc it will never be killed. in addition, the application_master process will never be killed
• if a process is considered part of an application in thunderbeam_immune_app it will never be killed
• if sending the 'seppuku' atom as a message to a process with the trap_exit flag set does not cause it to quit and the thunderbeam_force_kill config variable is set to true then it will be sent a 'kill' exit signal

For hotbeam the configuration is interpreted as follows

• Source files are only monitored if hotbeam_compile is true
• Only modules in the applications listed in hotbeam_apps are monitored

For shellbeam the configuration is interpreted as follows

• Specified modules are used to determine loaded commands for top level shell and changes are not detected until shell is restarted
• Ansi coloring will take effect immediately however only works reliably from a ssh shell
• Prompt will take effect immediately

As the SSH server is loaded during execution of the OTP application callback the configuration is not loaded via the hook. This must be specified as OTP application environment config. The configuration is interpreted as follows

• Will only be started if set as true
• Will bind to the specified port
• If path is not set then it will attempt to use the priv directory followed by the users home directory followed by /tmp. The suffix '.magicbeam' will be appended to any automatically interpreted path. If the host keys do not exist then they will be created. Be sure to create an authorized_keys file!

There are two optional integration points for existing applications. The callback hook module is specified either by the 'callback' application environment variable or on the command line when remotely injecting via the escript. In addition, you may include the helpers.hrl file and make use of the magicbeam_handle_info macro to implement a gen_server:handle_info/2 callback function. This will cause a gen_server which has the trap_exit flag set to terminate upon receipt of the single atom 'seppuku' with a non-normal reason.

The hook should implement the 'magicbeam' behaviour. In lieu of edocs the API is roughly as follows.

This function is meant to perform whatever initialization your hook needs. It returns an opaque variable which will be passed into other callback functions.

This function is called when magicbeam performs actions. In case you care as much about logging and metrics as I do.

This function is used to override the default usage of application environment for configuration.

Called when the magicbeam application is shutting down.

Thanks to the following people / organizations

• Justin Kirby for inspiration on the k-rad means of creating an escript that injects beams into a running node
• Juan Jose Comellas for the getopt module
• Basho because rebar is awesome