diff --git a/docs/source/the_project/install_and_configure.rst b/docs/source/the_project/install_and_configure.rst index 0de1c9a..f995169 100644 --- a/docs/source/the_project/install_and_configure.rst +++ b/docs/source/the_project/install_and_configure.rst @@ -1,7 +1,7 @@ Installing Kapow! ================= -*Kapow!* has a reference implementation in ``Go`` that is under active development +*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. @@ -20,7 +20,7 @@ Linux Install the downloaded binary using the following command as a privileged user. -.. code-block:: bash +.. code-block:: console $ install -t /usr/local/bin/kapow path_to_downloaded_binary @@ -32,22 +32,50 @@ Copy the downloaded binary to a directory of your choice and update the system ``PATH`` variable to include that directory. -Install the package with go get -------------------------------- +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: -.. code-block:: bash +.. code-block:: console - $ go get -u github.com/BBVA/kapow + $ go get -v github.com/BBVA/kapow + +Note that *Kapow!* leverages *Go modules*, so you can target specific releases: + +.. code-block:: console + + $ GO111MODULE=on go get -v github.com/BBVA/kapow@v0.3.0-rc4 + go: finding github.com v0.3.0-rc4 + go: finding github.com/BBVA v0.3.0-rc4 + go: finding github.com/BBVA/kapow v0.3.0-rc4 + go: downloading github.com/BBVA/kapow v0.3.0-rc4 + go: extracting github.com/BBVA/kapow v0.3.0-rc4 + github.com/google/shlex + github.com/google/uuid + github.com/spf13/pflag + github.com/BBVA/kapow/internal/server/httperror + github.com/BBVA/kapow/internal/http + github.com/BBVA/kapow/internal/server/model + github.com/BBVA/kapow/internal/client + github.com/gorilla/mux + github.com/BBVA/kapow/internal/server/user/spawn + github.com/BBVA/kapow/internal/server/data + github.com/BBVA/kapow/internal/server/user/mux + github.com/BBVA/kapow/internal/server/user + github.com/BBVA/kapow/internal/server/control + github.com/spf13/cobra + github.com/BBVA/kapow/internal/server + github.com/BBVA/kapow/internal/cmd + github.com/BBVA/kapow 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 +If you want to include *Kapow!* in a ``Docker`` image, you can add the binary +directly from the releases section. Below is an example ``Dockerfile`` that includes *Kapow!*. .. code-block:: dockerfile @@ -63,15 +91,15 @@ includes *Kapow!*. ENTRYPOINT ["/usr/bin/kapow"] 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. +configure it, remember to include a ``--control-bind`` param with an external +bind address (e.g., ``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: -.. code-block:: bash +.. code-block:: console $ 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 +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 390ca5f..8e4979a 100644 --- a/docs/source/the_project/quickstart.rst +++ b/docs/source/the_project/quickstart.rst @@ -19,15 +19,18 @@ this: Our organization has an external host that acts as a bridge between our intranet an the public Internet. -**Our goal: Our team needs to check if the** :samp:`Internal Host` **is alive.** +**Our goal: Our team must be able to check if the :samp:`Internal Host` is alive on an ongoing basis.** 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 :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. +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. @@ -35,7 +38,7 @@ Limitations and Constraints The Desired Solution -------------------- -After analyzing the problem and our with our goal in mind, we conclude that it +After analyzing the problem and 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.** @@ -44,9 +47,9 @@ 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 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`. +If we choose this option, then, for every person that needs to check the status +of :samp:`Internal host`, we need to create a user in the ``Extarnal Host`` and +grant them ``SSH`` access. Conclusion: **Not a good idea.** @@ -80,10 +83,14 @@ Using *Kapow!* (spoiler: it's the winner!) Ok, let's analyze *Kapow!* and check if it is compatible with our constraints: -1. *Kapow!* is Open Source, so **it's also free as in beer**. -2. By using kapow! we don't need to code 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`. +1. *Kapow!* is Open Source, so it's also **free as in beer**. +2. By using *Kapow!* we don't need to code 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** :samp:`External Host` **to + anybody**. Conclusion: *Kapow!* **is the best choice.** @@ -93,19 +100,20 @@ Reasons: It satisfies all of our requirements. Using Kapow! ------------ -In order to get our example :ref:`Scenario ` working we need to follow the below steps. +In order to get our example :ref:`Scenario ` working we need +to follow the steps below. Install Kapow! ++++++++++++++ -Follow :doc:`Install *Kapow!* ` instructions. +Follow the :doc:`Installing Kapow! ` instructions. Write a ``ping.pow`` File +++++++++++++++++++++++++ -*Kapow!* uses plain text files (called ``POW`` files) so you can define the +*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: @@ -116,16 +124,21 @@ 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. -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. +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 output of `ping` to the body + of the response, so you can see it. 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 diff --git a/docs/source/the_project/security.rst b/docs/source/the_project/security.rst index 83dfcec..061ee80 100644 --- a/docs/source/the_project/security.rst +++ b/docs/source/the_project/security.rst @@ -23,8 +23,8 @@ Let's consider the following route: #!/bin/sh kapow route add /find -c <<-'EOF' - BASEPATH=$(kapow get /request/params/path) - find "$BASEPATH" | kapow set /response/body + BASEPATH=$(kapow get /request/params/path) + find "$BASEPATH" | kapow set /response/body EOF @@ -61,12 +61,11 @@ The command that will eventually be executed by ``bash`` is: find -delete | kapow set /response/body -This will silently delete all the files below the current directory, no +This will *silently delete all the files below the current directory*, no questions asked. Probably not what you expected. This happens because ``find`` has the last word on how to interpret its arguments. -For ``find`` the argument `-delete` is not a path, - +For ``find``, the argument `-delete` is not a path. Let's see how we can handle this particular case: @@ -74,13 +73,13 @@ Let's see how we can handle this particular case: #!/bin/sh kapow route add /find -c <<-'EOF' - USERINPUT=$(kapow get /request/params/path) - BASEPATH=$(dirname -- "$USERINPUT")/$(basename -- "$USERINPUT") - find "$BASEPATH" | kapow set /response/body + USERINPUT=$(kapow get /request/params/path) + BASEPATH=$(dirname -- "$USERINPUT")/$(basename -- "$USERINPUT") + find "$BASEPATH" | kapow set /response/body EOF .. note:: Since this is critical for keeping your *Kapow!* services secure, we are working on a way to make this more transparent and safe, while at the same time keeping - it Kapowy. + it *Kapowy*. diff --git a/docs/source/tutorial/index.rst b/docs/source/tutorial/index.rst index 98aa4f5..ea353b4 100644 --- a/docs/source/tutorial/index.rst +++ b/docs/source/tutorial/index.rst @@ -1,13 +1,13 @@ *Kapow!* Tutorial ================= - This tutorial will allow you to grow slowly in the knowledge of *Kapow!*. It - tells you the story of a senior ops guy just arrived to his new job in a small - company. He'll face different challenges of increasing difficulty, but with - the help of his experienced senior mate and *Kapow!* he will be able to satisfy - all the requierements. + This tutorial will help you to get more familiar with *Kapow!*. It tells you + the story of a senior ops guy just arrived to his new job in a small company. + He'll face different challenges of increasing difficulty, but with the help of + his experienced senior mate and *Kapow!* he will be able to pass all the + hurdles. - You just only need to follow the steps and execute the code shown in the - tutorial to learn the *Kapow!* way of doing. + You just need to follow the steps and execute the code shown in the tutorial + to learn *the Kapow! way*. - Have a nice trip to Kapow! + Enjoy the ride!