Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 162 lines (125 sloc) 6.354 kB
d678d38 @pfischermx Initial commit and approved by Y!
pfischermx authored
1 NAME
2 App::Foca::Server - Foca server
3
4 DESCRIPTION
5 Foca is an application (a HTTP server using HTTP::Daemon) that allows
6 the execution of pre-defined commands via, obviously, HTTP.
7
8 Well, lets suppose you have a log parser on all your servers and you are
9 in need to parse all of them, the common way would be to ssh to each
10 host (can be as simple as ssh'ing to each host or using a multiplex
11 tool) and execute your parser, but what if your SSH keys or the keys of
12 a user are not there? It will be a heck of pain to enter your password
13 hundred of times or lets imagine you want to parse your logs via some
14 automation (like doing it from an IRC bot or tied to your monitoring
15 solution).. then the problem comes more complex with SSH and private
16 keys. With Foca you don't need to worry about those things, the command
17 will get executed and the output will be returned as a HTTP response.
18
19 All commands that Foca knows about it are listed in a YAML file. Foca
20 uses a default timeout value for all commands but with this YAML file
21 you can give a specific timeout to a specific command. All commands are
22 executed with IPC (open3).
23
24 Now the question is.. is Foca secure? Well it depends on you. Depends if
25 you run it as non-root user and the commands you define. Foca will try
26 to do things to protect, for example it will reject all requests that
27 have pipes (|), I/O redirection (>, <, <<, >>), additionally the HTTP
28 request will be validated before it gets executed via the call of
29 "validate_request()" (App::Foca returns true all the time so if you want
30 to add extra functionality please create a subclass and re-define the
31 method).
32
33 EXAMPLE
34 my $server = App::Foca::Server->new(
35 port => $port,
36 commands_file => $commands,
37 commands_timeout => $timeout,
38 debug => $debug);
39
40 $server->run_server();
41
42 EXAMPLE COMMANDS FILE
43 commands_dirs:
44 - /some/path/over/there/bin
45
46 commands:
47 df_path:
48 cmd: '/bin/df {%foca_args%} | tail -n1'
49 uptime:
50 cmd: '/usr/bin/uptime'
51 'true':
52 cmd: '/bin/true'
53
54 The way the example commands file work is: First it will look if there
55 is a *commands_dir* key, this key should have a list of directories
56 (that means it should be an array reference), Foca will look for all
57 executables inside the given directories and add them into memory.
58 Second, it will look for the *commands* key, this one should be a hash
59 where each key is the name of the command and it should have at least a
60 *cmd* key which value should be the *real* command to execute.
61
62 Please note that when you use the *commands_dir*, Foca will use the
63 basename of each executable as the name of the command so if you have
64 /usr/local/foo, the foca command will be *foo* while the command it will
65 execute will be */usr/local/foo*.
66
67 Also, you can override commands found in *commands_dir* via *commands*,
68 so going back to our /usr/local/foo example, you can have this
69 executable in your /usr/local directory but also have a *foo* command
70 defined in *commands*, the one that is defined in *commands* will be the
71 one that will be used by Foca.
72
73 There are two ways to update the list of commands once the server
74 started: One is by obviously restarting it and the other one is via
75 localhost send a HTTP request to localhost:yourport/reload.
76
77 Attributes
78 commands_file
79 YAML file with the supported commands.
80
81 commands
82 Hash reference with a list of supported commands. Basically the
83 content of "commands_file".
84
85 port
86 Where to listen for requests?
87
88 commands_timeout
89 Global timeout for all commands. Default to 1min (60 seconds).
90
91 tmp_dir
92 Temporary directory, for cache.
93
94 debug
95 Debug/verbose mode, turned off by default.
96
97 server
98 App::Foca::Server::HTTP object.
99
100 cache
101 For mmap cache (so we can share cache across processes).
102
103 Methods
104 run_server()
105 Runs the HTTP::Daemon server. it forks on each request.
106
107 prepare_status_response()
108 Prepares a response (HTTP::Response) for the /status request. /status
109 requests returns some stats about Foca server, such as: number of active
110 connections, number of closed/zombie connections (user connected and
111 left the connection open with a process that is no longer needed).
112
113 prepare_foca_response($connection, $request)
114 Prepares a response (HTTP::Response) for a given foca request
115 (HTTP::Request).
116
117 build_response($code, $body)
118 Builds a HTTP response ("HTTP::Response") based on the given HTTP status
119 code and optionally adds a body.
120
121 Returns a "HTTP::Response" so it can be send via the opened connection.
122
123 validate_request($command, $request)
124 re-define this method if you want to add some extra security. By default
125 all requests are valid at this point.
126
127 run_cmd($connection, $name, $cmd, $params)
128 Runs whatever the command is and sets a timeout to it. If it takes too
129 long then it will try to kill the process.
130
131 Depending on the settings given to the command it will return the STDOUT
132 or STDERR or even both. The rules are:
133
134 1. On success it will look for STDOUT, if nothing is there then it looks
135 in STDERR. If nothing is foudn in STDERR and STDOUT then an empty string
136 is returned.
137 2. On error it will look for STDERR first, if nothing is there then it
138 looks in STDOUT. If nothing is there then it returns an empty string.
139
140 Both STDOUT and STDERR can be returned if the command is defined as
141 follows:
142
143 server_uptime:
144 cmd: '/usr/bin/uptime'
145 capture_all: 'y'
146
147 load_commands()
148 Load the commands YAML file and stores it in memory with Cache::FastMnap
149
150 COPYRIGHT
151 Copyright (c) 2010-2012 Yahoo! Inc. All rights reserved.
152
153 LICENSE
154 This program is free software. You may copy or redistribute it under the
155 same terms as Perl itself. Please see the LICENSE file included with
156 this project for the terms of the Artistic License under which this
157 project is licensed.
158
159 AUTHORS
160 Pablo Fischer (pablo@pablo.com.mx)
161
Something went wrong with that request. Please try again.