From 7fab8ae52986c03243996bb38d69b77de488c512 Mon Sep 17 00:00:00 2001 From: luissaiz Date: Fri, 29 Nov 2019 09:48:10 +0100 Subject: [PATCH] Update quickstart.rst --- docs/source/the_project/quickstart.rst | 138 ++++++++++--------------- 1 file changed, 57 insertions(+), 81 deletions(-) diff --git a/docs/source/the_project/quickstart.rst b/docs/source/the_project/quickstart.rst index 7f10254..cb468b1 100644 --- a/docs/source/the_project/quickstart.rst +++ b/docs/source/the_project/quickstart.rst @@ -1,111 +1,95 @@ -Quick Start Guide -================= - -We'll explain a simple example to help you understand what **Kapow!** can do and -why it is so awesome :-). +Quick start +=========== +We'll explain you a simple example to help you understand what Kapow! really does and why it is awesome. Scenario -------- -Let's suppose that we're in a corporate network like the following one: +In this example we'll consider that our scenario is a corporate network like this: .. _quickstart_image: .. image:: /_static/network.png :align: center :width: 80% -Our organization has an external host that act as a bridge between our intranet -an the public Internet. +Our organization has an external host as a bridge between our intranet an the public Internet. -**Our goal: We need to check if the** :samp:`Internal Host` **is alive.** +**Our goal: our team need to check if the the host :samp:`Internal Machine` is alive.** - -Limitations and Constraints ---------------------------- +Limitations and constrains +-------------------------- 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 :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. +2. We **don't want** to manage VPNs or any similar solutions to access to *Internal Host* from the Internet. +3. We **want to limit the actions** that an user can perform in our intranet when while it is checking if :samp:`Internal Host` is alive. +4. We **want** the most standard way mechanism. Easy to use and that facilitates the automation. +5. We **don't have budget** to invest in a custom solution. +Study options +------------- -The Desired Solution --------------------- +Alter analyze the problem and our goal we conclude that is enough **with 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, then **we need analyze how to perform the ping.** -So, the next step is to **analyze how to perform the ping.** +Accessing via SSH ++++++++++++++++++ +In this case we need to create a system user in samp:`External Host` for each user that needs to check if :samp:`Internal host` is alive and we also need to grant access to each user through :samp:`SSH` to the system. -Accessing via SSH to :samp:`External Host` -++++++++++++++++++++++++++++++++++++++++++ - -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.** +Conclusion: **Not good idea** Reasons: - 1. We need to manage users (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.) + 1. We need to manage users (violates our constrains) + 2. We need to access users to system (violates our constrains) + 3. We can't control the :samp:`ping` options the user choice to ping :samp:`Internal Host` (violates our constrains) +Develop custom solution ++++++++++++++++++++++++ -Develop and Deploy a Custom Solution -++++++++++++++++++++++++++++++++++++ +Oks, this approach could maybe be the more customizable for our organization but: -Ok, this approach could be the best choice for our organization, but: +1. We'll need to start a new project. Develop it, test it, manage it and maintain it. +2. We need time for the development. +3. We need money. Even we have developers in our organization, their time it's not free. -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 budget, even if we have developers in our organization. - -Conclusion: **Not a good idea.** +Conclusion: **Not good idea** Reasons: -1. Need to spend money (violates a constraint.) -2. Need to spend time (and time is money, see reason #1) + 1. Need to spend money (violates our constrains) + 2. Need to spend time (violates our constrains) +Using Kapow! (Spoiler: the winner!) ++++++++++++++++++++++++++++++++++++ -Using Kapow! (spoiler: it's the winner!) -++++++++++++++++++++++++++++++++++++++++ +Oks, lets analyze Kapow! and check our constrains: -Ok, lets analyze **Kapow!** and check if it is compatible with our constraints: +1. Kapow! is Open Source. Them: **it's free**. +2. By using kapow! we don't need to program our own solution. Them: **don't waste time**. +3. By using Kapow! we can run any command in the :samp:`External Host` limiting the command parameters. Them: **it's safe**. +4. By using Kapow! we can launch any system command as HTTP API easily. Them: **we don't need to grant login access to anybody to :samp:`External Host`** -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`. - -Conclusion: **Kapow! is the best choice.** - -Reasons: It satisfies all of our requirements. +Conclusion: **Kapow! is the best choice**. +Reasons: it cover all of our requirements. Using Kapow! ------------ -In order to get our example :ref:`Scenario ` working we need to follow the below steps. - +Following the example of the :ref:`Scenario ` we'll follow these steps: Install Kapow! ++++++++++++++ -Follow :doc:`Install Kapow! ` instructions. +Follow :doc:`Install Kapow! `. +Write ping.pow file ++++++++++++++++++++ -Write a `ping.pow` File -+++++++++++++++++++++++ - -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: +Kapow! use plain text files to define the rules to expose the system command. For our example we need a file like that: .. code-block:: console @@ -114,27 +98,24 @@ file like this: 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 endpoint is invoked. +1. :samp:`kapow route add /ping` - adds a new HTTP API end-point at :samp:`/ping`. +2. :samp:`-c` - after this parameter we write the system command that Kapow! will runs for each HTTP Request to :samp:`/ping`. 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 output of `ping` to the body of the response, so you can see it. +4. :samp:`| kapow set /response/body` - sends the ping response to be the HTTP Response of HTTP End-point of :samp:`/ping`. - -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 :samp:`simple.pow`: .. code-block:: console $ kapow server ping.pow - -Consume the Service +Consume the service +++++++++++++++++++ -Now we can call our newly created endpoint by using our favorite HTTP client. -In this example we're using :samp:`curl`: +Then we can call HTTP Service as any usual tool for the web. In this example we'll use :samp:`curl`: .. code-block:: console @@ -142,18 +123,13 @@ In this example we're using :samp:`curl`: 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 +++++++++++++++++ - -Under the Hood -++++++++++++++ - -To understand what's happening under the hood with **Kapow!** lets see the -following diagram: +To understand what's happening in the hoods with Kapow! lets see the picture: .. image:: /_static/sequence.png :align: center :width: 80% -As you can see, **Kapow!** provides the necessary *magic* to turn a **system -command** into an ``HTTP API``. +As you can see, Kapow! perform the *magic* between system commands and HTTP API.