view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    App::Foca::Server - Foca server

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
    "validate_request()" (App::Foca returns true all the time so if you want
    to add extra functionality please create a subclass and re-define the
    method).

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

        $server->run_server();

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 *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 *commands* key, this one should be a hash
    where each key is the name of the command and it should have at least a
    *cmd* key which value should be the *real* command to execute.

    Please note that when you use the *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 *foo* while the command it will
    execute will be */usr/local/foo*.

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