28f0ae03d5
* doc/README.md: - Fix a couple of typos. - Fix spacing and shell quote style (for consistency with other markdown docs already in the tree). - Fix indent with spaces not tabs in heredocs with <<- style¹. - Fix shell example partially inserted twice. * doc/*.pow: - Fix indent with spaces not tabs in heredocs with <<- style¹. ¹: See the last paragraph in https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Here-Documents "If the redirection operator is ‘<<-’, then all leading tab characters are stripped from input lines and the line containing delimiter. This allows here-documents within shell scripts to be indented in a natural fashion."
227 lines
6.1 KiB
Markdown
227 lines
6.1 KiB
Markdown
# Installing Kapow!
|
||
|
||
Kapow! has a reference implementation in Go that is under active development right
|
||
now. If you want to start using Kapow! you can:
|
||
* Download a binary (linux, at this moment) from our
|
||
[releases](https://github.com/BBVA/kapow/releases) section
|
||
* Install the package with the `get` command (you need the Go runtime installed
|
||
and [configured](https://golang.org/cmd/go/))
|
||
```sh
|
||
go get -u github.com/BBVA/kapow
|
||
```
|
||
|
||
|
||
# Examples
|
||
|
||
Below are some examples on how to define and invoke routes in Kapow!
|
||
|
||
As you will see `kapow` binary is both a server and a CLI that you can use to configure
|
||
a running server. The server exposes an [API](/spec#http-control-api) that you
|
||
can use directly if you want.
|
||
|
||
In order to get information from the request that fired the script execution and
|
||
to help you compose the response, the server exposes
|
||
some [resources](/spec#handlers) to interact with from the script.
|
||
|
||
|
||
## The mandatory Hello World (for WWW fans)
|
||
|
||
First, you create a pow file named `greet.pow` with the following contents:
|
||
```sh
|
||
kapow route add /greet -c 'name=$(kapow get /request/params/name); echo Hello ${name:-World} | kapow set /response/body'
|
||
```
|
||
|
||
note that you have to escape it as the command will run on a shell itself. Then, you
|
||
execute:
|
||
```sh
|
||
kapow server greet.pow
|
||
```
|
||
|
||
to start a Kapow! server exposing your service. Now you can check that it works
|
||
as intended with good ole’ `curl`:
|
||
```sh
|
||
curl localhost:8080/greet
|
||
Hello World
|
||
|
||
curl localhost:8080/greet?name=friend
|
||
Hello friend
|
||
```
|
||
|
||
If you want to work with JSON you can use this version of the pow
|
||
`greet-json.pow`
|
||
```sh
|
||
kapow route add -X POST /greet -c 'who=$(kapow get /request/body | jq -r .name); kapow set /response/status 201; jq --arg value "${who:-World}" -n \{name:\$value\} | kapow set /response/body'
|
||
```
|
||
|
||
that uses [jq](https://stedolan.github.io/jq/) to allow you to work with JSON
|
||
from the command line. Check that it works with
|
||
```sh
|
||
curl -X POST -H 'Content-Type: application/json' -d '{"name": "friend"}' localhost:8080/greet
|
||
{"name": "friend" }
|
||
|
||
curl -X POST -H 'Content-Type: application/json' -d '' localhost:8080/greet
|
||
{"name": "World"}
|
||
```
|
||
|
||
|
||
## The mandatory Echo (for UNIX fans)
|
||
|
||
First, you create a pow file named `echo.pow` with the following contents:
|
||
```sh
|
||
kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
|
||
```
|
||
|
||
then, you execute:
|
||
```sh
|
||
kapow server echo.pow
|
||
```
|
||
|
||
and you can check that it works as intended with good ole’ `curl`:
|
||
```sh
|
||
curl -X POST -d '1,2,3... testing' localhost:8080/echo
|
||
1, 2, 3, 4, 5, 6, 7, 8, 9, testing
|
||
```
|
||
|
||
If you send a big file and want to see the content back as a real-time stream
|
||
you can use this version `echo-stream.pow`
|
||
```sh
|
||
kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/stream'
|
||
```
|
||
|
||
|
||
## The multiline fun
|
||
|
||
Unless you're a hardcore Perl golfer, you'll probably need to write your stuff
|
||
over more than one line in order to avoid the mess we saw on our JSON greet
|
||
version.
|
||
|
||
Don't worry, we need to write several lines, too. Bash, in its magnificent
|
||
UNIX® style, provides us with the
|
||
[here-documents](https://www.gnu.org/software/bash/manual/bash.html#Here-Documents)
|
||
mechanism that we can leverage precisely for this purpose.
|
||
|
||
Imagine that we want to return both the standard output and a generated file from a
|
||
command execution. Let's write a `log-and-stuff.pow` file with the following content:
|
||
```sh
|
||
kapow route add /log_and_stuff - <<-'EOF'
|
||
echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body
|
||
cat log.txt | kapow set /response/body
|
||
EOF
|
||
```
|
||
|
||
then we serve it with `kapow`:
|
||
```sh
|
||
kapow server log-and-stuff.pow
|
||
```
|
||
|
||
Yup. As simple as that. You can check it.
|
||
```sh
|
||
curl localhost:8080/log_and_stuff
|
||
this is a quite long sentence and other stuff
|
||
this is a quite long sentence and other stuff
|
||
```
|
||
|
||
|
||
## Interact with other systems
|
||
|
||
You can leverage all the power of the shell in your scripts and interact with
|
||
other systems by using all the available tools. Write a
|
||
`log-and-stuff-callback.pow` file with the following content:
|
||
```sh
|
||
kapow route add /log_and_stuff - <<-'EOF'
|
||
callback_url="$(kapow get /request/params/callback)"
|
||
echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body
|
||
echo sending to $callback_url | kapow set /response/body
|
||
curl -X POST --data-binary @log.txt $callback_url | kapow set /response/body
|
||
EOF
|
||
```
|
||
|
||
serve it with `kapow`:
|
||
```sh
|
||
kapow server log-and-stuff-callback.pow
|
||
```
|
||
|
||
and finally check it.
|
||
```sh
|
||
curl localhost:8080/log_and_stuff?callback=nowhere.com
|
||
this is a quite long sentence and other stuff
|
||
sending to nowhere.com
|
||
<html>
|
||
<head><title>405 Not Allowed</title></head>
|
||
<body>
|
||
<center><h1>405 Not Allowed</h1></center>
|
||
<hr><center>nginx</center>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
You must be aware that you must have all the dependencies you use in your
|
||
scripts installed in the host that will run the Kapow! server.
|
||
|
||
In addition, a pow file can contain as many routes as you like, so you can start
|
||
a server with several routes configured in one shot.
|
||
|
||
|
||
# Sample Docker usage
|
||
|
||
## Clone the project
|
||
|
||
```sh
|
||
git clone https://github.com/BBVA/kapow.git
|
||
```
|
||
|
||
|
||
## Build the kapow! docker image
|
||
|
||
```sh
|
||
make docker
|
||
```
|
||
|
||
Now you have a container image with all the above pow files copied in /tmp so
|
||
you can start each example by running
|
||
```sh
|
||
docker run --rm -p 8080:8080 docker server example.pow
|
||
```
|
||
|
||
|
||
## Build a docker image for running the nmap example
|
||
```sh
|
||
cd /path/to/kapow/poc/examples/nmap; docker build -t kapow-nmap .
|
||
```
|
||
|
||
|
||
## Run kapow
|
||
```sh
|
||
docker run \
|
||
-d \
|
||
-p 8080:8080 \
|
||
kapow-nmap
|
||
```
|
||
which will output something like this:
|
||
```sh
|
||
e7da20c7d9a39624b5c56157176764671e5d2d8f1bf306b3ede898d66fe3f4bf
|
||
```
|
||
|
||
|
||
## Test /list endpoint
|
||
|
||
In another terminal, try running:
|
||
```sh
|
||
curl http://localhost:8080/list/github.com
|
||
```
|
||
|
||
which will respond something like:
|
||
```sh
|
||
Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC
|
||
Nmap scan report for github.com (140.82.118.3)
|
||
rDNS record for 140.82.118.3: lb-140-82-118-3-ams.github.com
|
||
Nmap done: 1 IP address (0 hosts up) scanned in 0.04 seconds
|
||
```
|
||
|
||
et voilà !
|
||
|
||
|
||
# License
|
||
|
||
This project is distributed under the [Apache License 2.0](/LICENSE).
|