From 53b326cb7b62aadb7a2a13a5d58a6d2c82192857 Mon Sep 17 00:00:00 2001 From: pancho horrillo Date: Wed, 27 Nov 2019 16:07:23 +0100 Subject: [PATCH] doc: style fixes, example code fixes and clarifications --- docs/source/examples/index.rst | 199 ++++++++++-------- docs/source/index.rst | 21 +- .../the_project/install_and_configure.rst | 32 +-- docs/source/the_project/quickstart.rst | 88 ++++---- 4 files changed, 193 insertions(+), 147 deletions(-) diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index 7c73717..7a75c60 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -1,9 +1,11 @@ -Using a .pow file +Using a .pow File +++++++++++++++++ -A .pow file is a plain text with shell instructions, usually, you can use Kapow! +A ``.pow`` file is just a ``bash`` script, where you make calls to the ``kapow route`` +command. -**Starting Kapow! using .pow file** + +**Starting Kapow! using a .pow file** .. code-block:: console :linenos: @@ -19,20 +21,22 @@ With the example.pow: # # This is a simple example of a .pow file # - echo "[*] Starting my script" + echo '[*] Starting my script' # We add 2 Kapow! routes - kapow route add '/my/route' -c 'echo "hello world" | kapow set /response/body' - kapow route add -X POST /echo -c '"$(kapow get /request/body)" | kapow set /response/body' + kapow route add /my/route -c 'echo hello world | kapow set /response/body' + kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body' .. note:: - Every manage task you with Kapow! could be done by .pow file + **Kapow!** can be fully configured using just ``.pow`` files -Load more than 1 .pow file -++++++++++++++++++++++++++ -You can load more than one .pow file at time. This can help you have your .pow files ordered. +Load More Than One ``.pow`` File +++++++++++++++++++++++++++++++ + +You can load more than one .pow file at time. This can help you keep your +``.pow`` files tidy. .. code-block:: console :linenos: @@ -41,19 +45,22 @@ You can load more than one .pow file at time. This can help you have your .pow f example-1.pow example-2.pow $ kapow server <(cat pow-files/*.pow) -Add a new route + +Add a New Route +++++++++++++++ .. warning:: - Be aware when you defined more than routes in same path, only first routed added will be resolved. + Be aware that if you register more than one route with same path, only the + first route added will be used. For example, if you add these routes: 1. http://localhost:8080/echo 2. http://localhost:8080/echo/{message} - Only first one route will be resolved. + only first one will be used. + **GET route** @@ -62,7 +69,8 @@ Defining route: .. code-block:: console :linenos: - $ kapow route add '/my/route' -c 'echo "hello world" | kapow set /response/body' + $ kapow route add /my/route -c 'echo hello world | kapow set /response/body' + Calling route: @@ -72,6 +80,7 @@ Calling route: $ curl http://localhost:8080/my/route hello world + **POST route** Defining route: @@ -79,15 +88,17 @@ Defining route: .. code-block:: console :linenos: - $ kapow route add -X POST /echo -c '"$(kapow get /request/body)" | kapow set /response/body' + $ kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body' + Calling route: .. code-block:: console :linenos: - $ curl -d "hello world" -X POST http://localhost:8080/echo - hello world% + $ curl -d 'hello world' -X POST http://localhost:8080/echo + hello world + **Adding URL params** @@ -96,7 +107,8 @@ Defining route: .. code-block:: console :linenos: - $ kapow route add '/echo/{message}' -c '"$(kapow get /request/matches/message)" | kapow set /response/body' + $ kapow route add '/echo/{message}' -c 'kapow get /request/matches/message | kapow set /response/body' + Calling route: @@ -104,13 +116,13 @@ Calling route: :linenos: $ curl http://localhost:8080/echo/hello%20world - hello world% + hello world -Listing routes +Listing Routes ++++++++++++++ -You can list active route in kapow! server. +You can list the active routes in the **Kapow!** server. .. _examples_listing_routes: @@ -118,9 +130,9 @@ You can list active route in kapow! server. :linenos: $ kapow route list - [{"id":"20c98328-0b82-11ea-90a8-784f434dfbe2","method":"GET","url_pattern":"/echo/{message}","entrypoint":"/bin/sh -c","command":"echo \"$(kapow get /request/matches/message)\" | kapow set /response/body","index":0}] + [{"id":"20c98328-0b82-11ea-90a8-784f434dfbe2","method":"GET","url_pattern":"/echo/{message}","entrypoint":"/bin/sh -c","command":"kapow get /request/matches/message | kapow set /response/body"}] -Or, for pretty output, you can use :samp:`jq`: +Or, if you want human-readable output, you can use :samp:`jq`: .. code-block:: console :linenos: @@ -132,31 +144,33 @@ Or, for pretty output, you can use :samp:`jq`: "method": "GET", "url_pattern": "/echo/{message}", "entrypoint": "/bin/sh -c", - "command": "\"$(kapow get /request/matches/message)\" | kapow set /response/body", - "index": 0 + "command": "kapow get /request/matches/message | kapow set /response/body", } ] .. note:: - Kapow! server has a administration interface, by default, listen at **localhost:8081** + **Kapow!** has an `HTTP` admin interface, by default listening at **localhost:8081** -Deleting routes +Deleting Routes +++++++++++++++ -If we want to delete a route you need their ID. Using de :ref:`listing routes example `, you can delete the route by typing: +You need the ID of a route to delete it. +Using the :ref:`listing routes example `, you can +obtain the ID of the route, and then delete it by typing: .. code-block:: console :linenos: $ kapow route remove 20c98328-0b82-11ea-90a8-784f434dfbe2 -Writing multiline .pow files -++++++++++++++++++++++++++++ -Some time you need to write more complex actions. So you can write multiline commands: +Writing Multiline ``.pow`` Files +++++++++++++++++++++++++++++++++ + +If you need to write more complex actions, you can leverage multiline commands: .. code-block:: console :linenos: @@ -169,28 +183,30 @@ Some time you need to write more complex actions. So you can write multiline com .. warning:: - Be aware with the **"-"** at the end of Kapow! command. It allows to read commands from the :samp:`stdin`. + Be aware of the **"-"** at the end of the ``kapow route add`` command. + It tells ``kapow route add`` to read commands from the :samp:`stdin`. .. warning:: - Multiline depends of the shell you're using (Bash by default). If you want to learn more of multiline see: `Here Doc `_ + If you want to learn more of multiline usage, see: `Here Doc + `_ -Add or modify an HTTP Header +Add or Modify an HTTP Header ++++++++++++++++++++++++++++ -Some times you want add some extra HTTP header to response. +You may want to add some extra HTTP header to the response. -In this example we'll adding the security header "nosniff" in a sniff.pow: +In this example we'll be adding the security header ``nosniff`` to the response. .. code-block:: console :linenos: $ cat sniff.pow kapow route add /sec-hello-world - <<-'EOF' - kapow set /response/headers/X-Content-Type-Options "nosniff" + kapow set /response/headers/X-Content-Type-Options nosniff - echo "more secure hello world" | kapow set /response/body + echo more secure hello world | kapow set /response/body EOF $ kapow server nosniff.pow @@ -220,42 +236,50 @@ Testing with curl: .. note:: - You can read more about nosniff header `here `_. + You can read more about the ``nosniff`` header `here + `_. -Modify JSON by using shell -++++++++++++++++++++++++++ + +Modify JSON by Using Shell Commands ++++++++++++++++++++++++++++++++++++ .. note:: - Nowadays webservices are json based so making your script json aware is probably a good choice. In order to be able to extract data from and compose json documents from a script you can use + Nowadays Web services are JSON-based so making your script JSON aware is + probably a good choice. In order to be able to extract data from a JSON + document as well as composing JSON documents from a script, you can leverage `jq `_. + **Example 1** -In this example our Kapow! service will receive a JSON value with an incorrect date, then our .pow file will fix then and return the correct value to the user. +In this example our **Kapow!** service will receive a JSON value with an incorrect +date, then our ``.pow`` file will fix it and return the correct value to the user. .. code-block:: console :linenos: $ cat fix_date.pow - kapow route add -X POST '/fix-date' - <<-'EOF' - kapow set /response/headers/Content-Type "application/json" - echo "$(kapow get /request/body)" | jq --arg newdate $(date +"%Y-%m-%d_%H-%M-%S") '.incorrectDate=$newdate' | kapow set /response/body + kapow route add -X POST /fix-date - <<-'EOF' + kapow set /response/headers/Content-Type application/json + kapow get /request/body | jq --arg newdate "$(date +'%Y-%m-%d_%H-%M-%S')"" '.incorrectDate=$newdate' | kapow set /response/body EOF -Call service with curl: +Call the service with ``curl``: .. code-block:: console :linenos: - $ curl -X POST http://localhost:8080/fix-date -H "Content-Type: application/json" -d '{"incorrectDate": "no way"}' + $ curl -X POST http://localhost:8080/fix-date -H 'Content-Type: application/json' -d '{"incorrectDate": "no way, Jose"}' { "incorrectDate": "2019-11-22_10-42-06" } + **Example 2** -In this example we extract the name field from the incoming json document in order to generate a two attribute json response. +In this example we extract the name field from the incoming JSON document in +order to generate a two-attribute JSON response. .. code-block:: console @@ -263,38 +287,39 @@ In this example we extract the name field from the incoming json document in ord kapow route add -X POST '/echo-attribute' - <<-'EOF' JSON_WHO=$(kapow get /request/body | jq -r .name) - kapow set /response/headers/Content-Type "application/json" + kapow set /response/headers/Content-Type application/json kapow set /response/status 200 - jq --arg greet "Hello" --arg value "${JSON_WHO:-World}" -n \{greet:\$greet\,to:\$value\} | kapow set /response/body - + jq --arg greet Hello --arg value "${JSON_WHO:-World}" --null-input '{ greet: $greet, to: $value }' | kapow set /response/body EOF -Call service with curl: +Call the service with ``curl``: .. code-block:: console :linenos: :emphasize-lines: 4 - $ curl -X POST http://localhost:8080/echo-attribute -H "Content-Type: application/json" -d '{"name": "MyName"}' + $ curl -X POST http://localhost:8080/echo-attribute -H 'Content-Type: application/json' -d '{"name": "MyName"}' { "greet": "Hello", "to": "MyName" } -Upload files + +Upload Files ++++++++++++ + **Example 1** -Upload a file using Kapow! is very simple: +Uploading a file using **Kapow!** is very simple: .. code-block:: console :linenos: $ cat upload.pow - kapow route add -X POST '/upload-file' - <<-'EOF' - echo "$(kapow get /request/files/data/content) | kapow set /response/body + kapow route add -X POST /upload-file - <<-'EOF' + kapow get /request/files/data/content | kapow set /response/body EOF .. code-block:: console @@ -302,9 +327,10 @@ Upload a file using Kapow! is very simple: $ cat results.json {"hello": "world"} - $ curl -X POST -H "Content-Type: multipart/form-data" -F "data=@results.json" http://localhost:8080/upload-file + $ curl -X POST -H 'Content-Type: multipart/form-data' -F data=@results.json http://localhost:8080/upload-file {"hello": "world"} + **Example 2** In this example we respond back with the line count of the file received in the request: @@ -316,14 +342,14 @@ In this example we respond back with the line count of the file received in the kapow route add -X POST '/count-file-lines' - <<-'EOF' # Get sent file - FNAME="$(kapow get /request/files/myfile/filename)" + FNAME=$(kapow get /request/files/myfile/filename) # Counting file lines - LCOUNT="$(kapow get /request/files/myfile/content | wc -l)" + LCOUNT=$(kapow get /request/files/myfile/content | wc -l) kapow set /response/status 200 - echo "$FNAME has $LCOUNT lines" | kapow set /response/body + echo $FNAME has $LCOUNT lines | kapow set /response/body EOF .. code-block:: console @@ -335,21 +361,24 @@ In this example we respond back with the line count of the file received in the $ curl -F "myfile=@file.txt" http://localhost:8080/count-file-lines file.txt has 2 lines + Protecting again Command Injection Attacks ++++++++++++++++++++++++++++++++++++++++++ -When you resolve variable values be careful to *escape* by using double quotes. Otherwise you could be vulnerable to **command injection attack**. +When you resolve variable values be careful to tokenize correctly by using +double quotes. Otherwise you could be vulnerable to **parameter injection +attacks**. -**This examples is VULNERABLE to command injection** +**This example is VULNERABLE to parameter injection** -In this example, an attacker can execute arbitrary command. +In this example, an attacker can inject arbitrary parameters to ``ls``. .. code-block:: console :linenos: $ cat command-injection.pow kapow route add '/vulnerable/{value}' - <<-'EOF' - ls "$(kapow get /request/matches/value)" | kapow set /response/body + ls $(kapow get /request/matches/value) | kapow set /response/body EOF Exploding using curl: @@ -357,17 +386,18 @@ Exploding using curl: .. code-block:: console :linenos: - $ curl "http://localhost:8080/vulnerable/;echo%20hello" + $ curl "http://localhost:8080/vulnerable/-li%20hello" -**This examples is NOT VULNERABLE to command injection** +**This examples is NOT VULNERABLE to parameter injection** -Be aware of we add double quotes when we recover *value* data from url: +Be aware of how we add double quotes when we recover *value* data from the +request: .. code-block:: console :linenos: $ cat command-injection.pow - kapow route add '/vulnerable/{value}' - <<-'EOF' + kapow route add '/not-vulnerable/{value}' - <<-'EOF' ls "$(kapow get /request/matches/value)" | kapow set /response/body EOF @@ -375,6 +405,7 @@ Be aware of we add double quotes when we recover *value* data from url: If want to read more about command injection, you can check `OWASP site `_ + Sending HTTP error codes ++++++++++++++++++++++++ @@ -421,7 +452,7 @@ In this example we'll redirect our users to Google: $ cat redirect.pow kapow route add '/redirect' - <<-'EOF' - kapow set /response/headers/Location 'http://google.com' + kapow set /response/headers/Location https://google.com kapow set /response/status 301 EOF @@ -446,10 +477,11 @@ In this example we'll redirect our users to Google: * Connection #0 to host localhost left intact -How to execute two processes parallel -+++++++++++++++++++++++++++++++++++++ +How to Execute Two Processes in Parallel +++++++++++++++++++++++++++++++++++++++++ -We want to :samp:`ping` two machines parallel. Kapow! get IPs from query params: +We want to :samp:`ping` two machines parallel. **Kapow!** gets IPs from query +params: .. code-block:: console :linenos: @@ -461,35 +493,36 @@ We want to :samp:`ping` two machines parallel. Kapow! get IPs from query params: wait EOF -Calling with curl: +Calling with ``curl``: .. code-block:: console :linenos: $ curl -v http://localhost:8080/parallel/10.0.0.1/10.10.10.1 -Manage cookies +Manage Cookies ++++++++++++++ -Sometimes you need track down some user state. Kapow! allows you manage Request/Response Cookies. +If you track down some user state, **Kapow!** allows you manage Request/Response +Cookies. -Next example we'll set a cookie: +In the next example we'll set a cookie: .. code-block:: console :linenos: $ cat cookie.pow kapow route add /setcookie - <<-'EOF' - CURRENT_STATUS="$(kapow get /request/cookies/kapow-status)" + CURRENT_STATUS=$(kapow get /request/cookies/kapow-status) - if [ -z "$CURRENT_SATUS" ]; then - kapow set /response/cookies/Kapow-Status "Kapow Cookie Set" + if [ -z "$CURRENT_STATUS" ]; then + kapow set /response/cookies/Kapow-Status 'Kapow Cookie Set' fi - echo "Ok" | kapow set /response/body + echo OK | kapow set /response/body EOF -Calling with curl: +Calling with ``curl``: .. code-block:: console :linenos: diff --git a/docs/source/index.rst b/docs/source/index.rst index c192226..c7dbd48 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,23 +16,24 @@ Welcome to Kapow! What's Kapow! ============= - Think of that **software** that you need but **only runs as command line**. - Kapow! lets you to **wrap it into an HTTP API without write a single line of - code**. + Think of that **software** that you need but **only runs in the command + line**. **Kapow!** lets you **wrap it into an HTTP API without writing a + single line of code**. .. image:: _static/kapow-quick-overview.png :width: 80% :align: center - Want to know more? Check the :doc:`the_project/quickstart` section for a long - explanation of what Kapow! does. + Want to know more? + Check the :doc:`the_project/quickstart` section for a longer explanation of + what **Kapow!** does. Authors ======= - **Kapow!** is being developed by - `BBVA-Labs Security team members `_. + **Kapow!** is being developed by the + `BBVA-Labs Security team `_. License @@ -51,7 +52,7 @@ Contributions Table of Contents -================ +================= .. toctree:: :maxdepth: 2 @@ -63,7 +64,7 @@ Table of Contents .. toctree:: :maxdepth: 2 - :caption: Usage examples + :caption: Usage Examples examples/index @@ -90,7 +91,7 @@ Table of Contents tutorial/tutorial04 tutorial/tutorial05 -Indices and tables +Indices and Tables ================== * :ref:`genindex` diff --git a/docs/source/the_project/install_and_configure.rst b/docs/source/the_project/install_and_configure.rst index 677327d..231fe60 100644 --- a/docs/source/the_project/install_and_configure.rst +++ b/docs/source/the_project/install_and_configure.rst @@ -1,18 +1,18 @@ 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 choose from several +Kapow! has a reference implementation in ``Go`` that is under active development +right now. If you want to start using **Kapow!** you can choose from several options. -Download and install a binary +Download and Install a Binary ----------------------------- -Binaries for several platforms are available from our +Binaries for several platforms are available from the `releases `_ section, visit the latest release page and download the binary corresponding to the platfom and -architecture you want to install Kapow! in. +architecture you want to install **Kapow!** in. Linux @@ -29,26 +29,26 @@ Windows ^^^^^^^ Copy the downloaded binary to a directory of your choice and update the system -PATH variable to include that directory. +``PATH`` variable to include that directory. Install the package with go get ------------------------------- If you already have `installed and configured `_ -the go runtime in the host where you want to run Kapow!, simply run: +the ``go`` runtime in the host where you want to run **Kapow!**, simply run: .. code-block:: bash $ go get -u github.com/BBVA/kapow -Include Kapow! in your container image +Include Kapow! in your Container Image -------------------------------------- -If you want to include Kapow! in a Docker image you can add the binary directly -from the releases section. Following is an example dockerfile that includes -Kapow!. +If you want to include **Kapow!** in a ``Docker`` image you can add the binary +directly from the releases section. Following is an example ``Dockerfile`` that +includes **Kapow!**. .. code-block:: dockerfile @@ -62,9 +62,9 @@ Kapow!. ENTRYPOINT ["/usr/bin/kapow"] -If the container is intended to run the server and you want to dinamically -configure it, remember to include a --control-bind param with an external bind -address (i.e. 0.0.0.0) and to map all the needed ports in order to get access +If the container is intended for running the server and you want to dinamically +configure it, remember to include a `--control-bind` param with an external bind +address (i.e. ``0.0.0.0``) and to map all the needed ports in order to get access to the control interface. After building the image you can run the container with: @@ -73,5 +73,5 @@ After building the image you can run the container with: $ docker run --rm -i -p 8080:8080 -v $(pwd)/whatever.pow:/opt/whatever.pow kapow:latest server /opt/whatever.pow -With the -v parameter we map a local file into the container's filesystem so we -can use it to configure our Kapow! server on startup. +With the `-v` parameter we map a local file into the container's filesystem so +we can use it to configure our **Kapow!** server on startup. diff --git a/docs/source/the_project/quickstart.rst b/docs/source/the_project/quickstart.rst index ef46a76..7f10254 100644 --- a/docs/source/the_project/quickstart.rst +++ b/docs/source/the_project/quickstart.rst @@ -1,38 +1,41 @@ -Quick start -=========== +Quick Start Guide +================= -We'll explain a simple example to help you understand what Kapow! really does and why it is awesome. +We'll explain a simple example to help you understand what **Kapow!** can do and +why it is so awesome :-). Scenario -------- -Consider that we're in a corporate network like the following one: +Let's suppose that we're in a corporate network like the following one: .. _quickstart_image: .. image:: /_static/network.png :align: center :width: 80% -Our organization has an external host that act as a bridget between our intranet an the public Internet. +Our organization has an external host that act as a bridge between our intranet +an the public Internet. **Our goal: We need to check if the** :samp:`Internal Host` **is alive.** -Limitations and constraints --------------------------- +Limitations and Constraints +--------------------------- 1. We **don't want** to **grant access** to the :samp:`External Host` to anybody. -2. We **don't want** to manage VPNs or any similar solutions to access to :samp:`Internal Host` from the Internet. -3. We **want to limit the actions** that an user can perform in our intranet while it is checking if :samp:`Internal Host` is alive. -4. We **want** to use the most standard mechanism. Easy to use and that facilitates the automation. +2. We **don't want** to manage VPNs or any similar solutions to access :samp:`Internal Host` from the Internet. +3. We **want to limit the actions** that a user can perform in our intranet while it is checking if :samp:`Internal Host` is alive. +4. We **want** to use the most standard mechanism. Easy to use and automate. 5. We **don't have a budget** to invest in a custom solution. -What options we have? ---------------------- +The Desired Solution +-------------------- -Alter analyzyng the problem and our goal we conclude that is enough **to use a simple** :samp:`ping` **to** :samp:`Internal Host`. +After analyzing the problem and our with our goal in mind, we conclude that it +is enough **to use a simple** :samp:`ping` **to** :samp:`Internal Host`. So, the next step is to **analyze how to perform the ping.** @@ -40,41 +43,43 @@ So, the next step is to **analyze how to perform the ping.** Accessing via SSH to :samp:`External Host` ++++++++++++++++++++++++++++++++++++++++++ -If we choose this option then we need to create a user and grant him access via :samp:`SSH` to :samp:`External Host` for every person that needs to check for :samp:`Internal host` status. +If we choose this option then we need to create a user in the host and grant +them access via :samp:`SSH` to :samp:`External Host` for every person that needs +to check the :samp:status of `Internal host`. Conclusion: **Not a good idea.** Reasons: 1. We need to manage users (violates a constraint.) - 2. We need to grant access for users to system (violates a constraint.) + 2. We need to grant usesrs access to a host (violates a constraint.) 3. We can't control what :samp:`ping` options the user can use to ping :samp:`Internal Host` (violates a constraint.) -Develop and deploy a custom solution +Develop and Deploy a Custom Solution ++++++++++++++++++++++++++++++++++++ -Ok, this approach could maybe be the better choice for our organization but: +Ok, this approach could be the best choice for our organization, but: 1. We'll need to create a new project, develop, test, manage and maintain it. 2. We need to wait for for the development to be production ready. -3. We need a bucket, even we have developers in our organization. +3. We need a budget, even if we have developers in our organization. Conclusion: **Not a good idea.** Reasons: 1. Need to spend money (violates a constraint.) -2. Need to spend time. +2. Need to spend time (and time is money, see reason #1) -Using Kapow! (Spoiler: the winner!) -+++++++++++++++++++++++++++++++++++ +Using Kapow! (spoiler: it's the winner!) +++++++++++++++++++++++++++++++++++++++++ -Ok, lets analyze Kapow! and check it for our constraints: +Ok, lets analyze **Kapow!** and check if it is compatible with our constraints: -1. Kapow! is Open Source, so **it's free**. -2. By using kapow! we don't need to program our own solution, so we **don't waste time**. +1. **Kapow!** is Open Source, so **it's also free as in beer**. +2. By using kapow! we don't need to program our own solution, so we **don't have to waste time**. 3. By using Kapow! we can run any command in the :samp:`External Host` limiting the command parameters, so **it's safe**. 4. By using Kapow! we can launch any system command as an HTTP API easily, so **we don't need to grant login access to anybody to** :samp:`External Host`. @@ -95,10 +100,12 @@ Install Kapow! Follow :doc:`Install Kapow! ` instructions. -Write ping.pow file -+++++++++++++++++++ +Write a `ping.pow` File ++++++++++++++++++++++++ -Kapow! use plain text files (called ``POW`` files) so you can define the endpoints you want to expose the system command with. For our example we need a file like this: +Kapow! uses plain text files (called ``POW`` files) so you can define the +endpoints you want to expose the system command with. For our example we need a +file like this: .. code-block:: console @@ -107,26 +114,27 @@ Kapow! use plain text files (called ``POW`` files) so you can define the endpoin Explanation: -1. :samp:`kapow route add /ping` - adds a new HTTP API endpoint at :samp:`/ping` path in the Kapow! server. You have to use GET method to invoke the endpoint. -2. :samp:`-c` - after this parameter we write the system command that Kapow! will run each time the endpint is invoked. +1. :samp:`kapow route add /ping` - adds a new HTTP API endpoint at :samp:`/ping` path in the Kapow! server. You have to use `GET` method to invoke the endpoint. +2. :samp:`-c` - after this parameter we write the system command that **Kapow!** will run each time the endpoint is invoked. 3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host *10.10.10.100*, i.e. :samp:`Internal Host`. -4. :samp:`| kapow set /response/body` - writes the ping output to the response so you can see it. +4. :samp:`| kapow set /response/body` - writes the output of `ping` to the body of the response, so you can see it. -Launch the service +Launch the Service ++++++++++++++++++ -At this point we only need to launch kapow! with our :samp:`ping.pow`: +At this point we only need to launch `kapow` with our :samp:`ping.pow`: .. code-block:: console $ kapow server ping.pow -Consume the service +Consume the Service +++++++++++++++++++ -Now we can call our new created endpoint by using our favorite HTTP client. In this example we're using :samp:`curl`: +Now we can call our newly created endpoint by using our favorite HTTP client. +In this example we're using :samp:`curl`: .. code-block:: console @@ -134,14 +142,18 @@ Now we can call our new created endpoint by using our favorite HTTP client. In t PING 10.10.100 (10.10.100): 56 data bytes 64 bytes from 10.10.100: icmp_seq=0 ttl=55 time=1.425 ms +et voilà ! -Under the hoods -++++++++++++++++ -To understand what's happening under the hoods with Kapow! lets see the picture: +Under the Hood +++++++++++++++ + +To understand what's happening under the hood with **Kapow!** lets see the +following diagram: .. image:: /_static/sequence.png :align: center :width: 80% -As you can see, Kapow! performs the *magic* between system commands and HTTP API. +As you can see, **Kapow!** provides the necessary *magic* to turn a **system +command** into an ``HTTP API``.