view release on metacpan or  search on metacpan

lib/App/Foca/Server.pm  view on Meta::CPAN

#
# App::Foca::Server
#
# Author(s): Pablo Fischer (pablo@pablo.com.mx)
# Created: 06/13/2012 01:44:57 AM UTC 01:44:57 AM
package App::Foca::Server;

=head1 NAME

App::Foca::Server - Foca server

=head1 DESCRIPTION

Foca is an application (a HTTP server using HTTP::Daemon) that allows the
execution of pre-defined commands via, obviously, HTTP.

Well, lets suppose you have a log parser on all your servers and you are in
need to parse all of them, the common way would be to ssh to each host (can
be as simple as ssh'ing to each host or using a multiplex tool) and execute
your parser, but what if your SSH keys or the keys of a user are not there?
It will be a heck of pain to enter your password hundred of times or lets
imagine you want to parse your logs via some automation (like doing it from
an IRC bot or tied to your monitoring solution).. then the problem comes
more complex with SSH and private keys. With Foca you don't need to worry
about those things, the command will get executed and the output will be
returned as a HTTP response.

All commands that Foca knows about it are listed in a YAML file. Foca uses a 
default timeout value for all commands but with this YAML file you can give
a specific timeout to a specific command. All commands are executed with IPC
(open3).

Now the question is.. is Foca secure? Well it depends on you. Depends if you
run it as non-root user and the commands you define. Foca will try to do
things to protect, for example it will reject all requests that have pipes (|),
I/O redirection (>, <, <<, >>), additionally the HTTP request will be validated
before it gets executed via the call of C<validate_request()> (L<App::Foca::Server>
returns true all the time so if you want to add extra functionality please
create a subclass and re-define the method).

=head1 EXAMPLE

    my $server = App::Foca::Server->new(
            port                => $port,
            commands_file       => $commands,
            commands_timeout    => $timeout,
            debug               => $debug);

    $server->run_server();

=head1 EXAMPLE COMMANDS FILE

    commands_dirs:
        - /some/path/over/there/bin

    commands:
        df_path:
            cmd: '/bin/df {%foca_args%} | tail -n1'
        uptime:
            cmd: '/usr/bin/uptime'
        'true':
            cmd: '/bin/true'

The way the example commands file work is: First it will look if there is a 
I<commands_dir> key, this key should have a list of directories (that means
it should be an array reference), Foca will look for all executables inside
the given directories and add them into memory. Second, it will look for the
I<commands> key, this one should be a hash where each key is the name of the
command and it should have B<at least> a I<cmd> key which value should be
the I<real> command to execute.

Please note that when you use the I<commands_dir>, Foca will use the basename
of each executable as the name of the command so if you have /usr/local/foo,
the foca command will be I<foo> while the command it will execute will be
I</usr/local/foo>.

Also, you can override commands found in I<commands_dir> via I<commands>, so
going back to our /usr/local/foo example, you can have this executable
in your /usr/local directory but also have a I<foo> command defined in 
I<commands>, the one that is defined in I<commands> will be the one that
will be used by Foca.