View source for Cloudy plug-ins

== What is a plug-in? ==

Cloudy is a Debian-based Linux distribution that provides users a simple and convenient web interface to manage different services that are to be used in a Community Network (in our case, Guifi).

At the same time, Cloudy offers a set of tools that allow a user to add a service to the system without need for advanced knowledges on networking or computers in general. These services are automatically published to the Community Network, so that anybody using Cloudy can use this new service.

'''Plug-ins''' are the modular pieces of code that allow adding and removing these services. Therefore, we understand thata plug-in is a program or a piece of software that a user can add to the Cloudy distribution and that can be managed in a simple way from the web interface provided by Cloudy.

== Adding services to Cloudy ==

=== A brief introduction ===

This guide will walk you through the process of adding a new service to Cloudy.

In order to be clear and provide examples, we are going to be integrating a very simple service showing snippets of code along the way.
To follow the tutorial or to add complex services, will be nice any knowledge of Bash<ref name="Bash">(http://www.tldp.org/LDP/Bash-Beginners-Guide/Bash-Beginners-Guide.pdf)</ref> and PHP<ref name="PHP">(https://php.net/manual/es/index.php)</ref>.

For the sake of simplicity, we will use Pastecat<ref name="Pastecat">(https://github.com/mvdan/pastecat)</ref>. It is a good candidate because:

* It's a standalone program
* It only needs to be installed in one node (no federation/syncrhonization)
* It's Built with Go, it's easy to distribute and deploy
* It doesn't need a configuration file nor any kind of setup
* It's very lightweight on resources

=== Getting the binary ===

The first thing we have to figure out is how to download and install the binary on Cloudy. Most software out there is already available as a package on Debian, but Pastecat isn't. If it were, it would be a matter of just running the command <code>apt-get install pastecat</code> from PHP. Therefore we'll have to get it from someplace else.

One option is to fetch the source and build it ourselves. This often means, however, that Cloudy should include a lot of build tools and libraries. In the case of Go, that would mean having its toolchain installed, which isn't very practical.

A better option when the Debian package isn't available is to download the binary from upstream trusted sources via HTTPS and, preferably, checking digests or using signatures. We can use Github's releases page for that. Both options leave us with an executable file that we should be able to run directly on Cloudy.

In this particular case we are going to download the binaries from the git repository with the following command line:

<pre>wget https://github.com/mvdan/pastecat/releases/download/v0.3.0/pastecat_linux_386</pre>
Note that in this case we are downloading a specific version for a Linux with a 386 architecture.

Note that having the service as a Debian package has many advantages:

* Updates are simple and need no extra work from Cloudy
* The package is compiled and built by Debian in a trusted way
* An init.d file is already provided
* Debian packages often contain small patches and fixes

=== Testing it out ===

Before adding Pastecat as a Cloudy service, we can configure and start it ourselves directly (i.e. manually), to see if it works and how. This way we can better understand what configuration options or command line parameters are we will need to run it as a service, and also to manage it once it is running.

=== Adding the controller ===

In <code>web/plug/controllers</code> we have one PHP file per service, which we call &quot;the controller&quot;. This is the code that will run when we enter the services page on the Cloudy web interface.

==== Adding the index function ====

We also want our service to be integrated in the Cloudy web structure. To do this, a few PHP scripts need to be created and added to our device. Altogether, and by the time being, we'll need to create a total of 2 scripts: <code>pastecat.PHP</code> and <code>pastecat.menu.PHP</code>. The first one is the controller itself, this is, the script that renders the page and has all the information such as buttons or redirections. The other one is what allows our service to show up in the upper menu bar of Cloudy's web interface.

The menu code will look like this:

<pre>&lt;?PHP
//peerstreamer.menu.PHP
addMenu('Pastecat','pastecat','Clommunity');</pre>
By now, we'll use a very simple PHP script in the controller:

<pre>&lt;?PHP
//pastecat
$title=&quot;Pastecat&quot;;

function index(){
    global $paspath,$title;
    global $staticFile;

    $page=hlc(t($title));
    $page .= hl(t(&quot;Minimalist pastebin engine written in Go&quot;),4);
    $page .= par(t(&quot;A simple and self-hosted pastebin service written in Go&quot;).' '.t(&quot;Can use a variety of storage backends&quot;).' '.t(&quot; Designed to optionally remove pastes after a certain period of time.&quot;).' '.(&quot;If using a persistent storage backend, pastes will be kept between runs.&quot;).' '.t(&quot;This software runs the&quot;).' '.&quot;&lt;a href='http://paste.cat'&gt;&quot;.t(&quot;paste.cat&quot;).&quot;&lt;/a&gt;&quot;. t(&quot; public service.&quot;));

    return(array('type' =&gt; 'render','page' =&gt; $page));
}</pre>
In our Cloudy system, these files must be placed at <code>/var/local/cDistro/plug/</code> the first one at <code>menus</code> directory and the second at <code>controllers</code> directory. Once we've done this, we can go to our Cloudy system and access our new Pastecat.

==== Making the controller install the service ====

As said before, this step is made much more easier if the service is packaged in Debian. Since Pastecat isn't, we'll have to do it manually. This usually involves a combination of <code>wget</code>, <code>mv</code> and <code>chmod</code>. It is generally a good idea to keep the service's files under <code>/opt/SERVICENAME</code>.

In our particular case, the first thing we need to do is downloading the binary from the release. In order to do this we will make use of the mentioned <code>wget</code> command. Given a URL to a file, this command allows us to download this file in our system, and this is what we will do in our system (as mentioned before):

<pre>wget https://github.com/mvdan/pastecat/releases/download/v0.3.0/pastecat_linux_386</pre>
Once we have the binary, we just need to move it to a directory where executable files use to be located. In our case, we will use the directory /opt/pastecat/. To move these files through our system we will use the command <code>mv</code>. However, first of all we need to create the directory where we will place our binary. To do this we use the <code>mkdir</code> command as is shown below:

mkdir -p /opt/pastecat/

Once we have our directory created, it is time to move the binary there:

<pre>mv current_directory/pastecat_linux_386 /opt/pastecat/</pre>
where current_directory is the directory where we previously downloaded the binary. Since the binary name depends on the architecture, in order to simplfy the controller's code, we will change its name to something more simple:

<pre>mv /opt/pastecat/pastecat_linux_386 /opt/pastecat/pastecat</pre>
Now our binary is called <code>pastecat</code> insted of <code>pastecat_linux_386</code>

These steps are the minimum requiered to install a service which is not provided in the Debian official repositories. However, to an end user, it would look like a nightmare to run these commands in a console connected through ssh to its device, so what we are going to do now, is create a bash script which will be called later from the web interface by clicking a button.

This script is the first version of the pastecat controller. For the time being, We will just include a function to install pastecat in a device. Later we will include some other functions to add more facilities to our service.

<pre>#!/bin/bash
PCPATH=&quot;/opt/pastecat/&quot;

doInstall() {
    if isInstall
    then
        echo &quot;Pastecat is already installed.&quot;
        return
    fi

    # Creating directory and switching
    mkdir -p $pcpath &amp;&amp; cd $pcpath

    # Getting file
    wget https://github.com/mvdan/pastecat/releases/download/v0.3.0/pastecat_linux_386

    # Changing name so controller can invoke it generically
    mv pastecat_linux_386 pastecat
    chmod +x pastecat
    
    cd -
}

isInstalled() {
    [ -d $pcpath ] &amp;&amp; return 0
    return 1
}


case $1 in
    &quot;install&quot;)
        shift
        doInstall $@
        ;;
esac</pre>
We can see how the lasts steps are done within the same function, allowing us to install the software in the device.

==== Making the controller use Pastecat ====

===== Start the service =====

The next thing we want is our software to be used through the web interface. In order to do this, we will include a new option to the main page of pastecat, and also integrate a new function to the controller script to manage the binary. We will add the button like this:

<pre>$page .= addButton(array('label'=&gt;t('Create a Pastecat server'),'href'=&gt;$staticFile.'/pastecat/publish'));</pre>
after the <code>Pastecat is installed</code> message. The next thing will be implementing the function <code>publish</code> in the same PHP. This function is the responsible of calling the appropiate function in the controller and to announce our server usign the avahi technology. The difference with this function is that it requieres a form to introduce data, so in the end we will have a total of 2 functions: a get and a post:

<pre>function publish_get() {
    global $pcpath,$title;
    global $staticFile;

    $page = hlc(t($title));
    $page .= hlc(t('Publish a pastecat server'),2);
    $page .= par(t(&quot;Write the port to publish your Pastecat service&quot;));
    $page .= createForm(array('class'=&gt;'form-horizontal'));
    $page .= addInput('description',t('Describe this server'));
    $page .= addSubmit(array('label'=&gt;t('Publish'),'class'=&gt;'btn btn-primary'));
    $page .= addButton(array('label'=&gt;t('Cancel'),'href'=&gt;$staticFile.'/peerstreamer'));

    return(array('type' =&gt; 'render','page' =&gt; $page));
}

function publish_post() {
    $port = $_POST['port'];
    $description = $_POST['description'];
    $ip = &quot;&quot;;

    $page = &quot;&lt;pre&gt;&quot;;
    $page .= _pcsource($description);
    $page .= &quot;&lt;/pre&gt;&quot;;

    return(array('type' =&gt; 'render','page' =&gt; $page));
}</pre>
As we can see, in the <code>post</code> function we are invoking another function. The reason to do this is to write a more simple and modular code. In this function, we are finally calling the script:

<pre>function _pcsource($port,$description) {
    global $pcpath,$pcprogram,$title,$pcutils,$avahi_type,$port;

    $page = &quot;&quot;;
    $device = getCommunityDev()['output'][0];
    $ipserver = getCommunityIP()['output'][0];

    if ($description == &quot;&quot;) $description = $type;

    $cmd = $pcutils.&quot; publish '$port' '$description';
    execute_program_detached($cmd);

    $page .= t($ipserver);
    $page .= par(t('Published this server.'));

    $page .= addButton(array('label'=&gt;t('Back'),'href'=&gt;$staticFile.'/pastecat'));

    return($page)
}</pre>
The next thing to do will be create the function <code>publish</code> in the controller, so we will add a new function to the basic controller we had back at section '''3.2'''. We will add a new flag called publish, so the first executed part of the script will look like this:

<pre>if [ $# -lt 1 ]
then
    doHelp
fi

case $1 in
    &quot;install&quot;)
        shift
        doInstall $@
        ;;
    &quot;publish&quot;)
        shift
        doServer $@
        ;;
esac</pre>
As we can see, when the script's first argument is <code>publish</code>, we shift the rest of arguments and call the function <code>doServer</code>. In this function, we must start the service with the requiered arguments, so the first thing we'll do is put the arguments into local variables. Once we do that the common thing would be to launche the Pastecat server, but since it might be called with root permissions (and this is bad) we must run it as a <code>nobody</code> user. The issue is that the <code>nobody</code> user has merely no permissions... and pastecat need some permissions to create folders and text files. In order to allow the <code>nobody</code> user to do that, first of all we will create a folder and grant permissions to almost everyone to it. We will use <code>chmod</code> again. Now, the user can create files and directories within this directory, so we can now run pastecat. Finally, we keep the pid in a variable in case we want to use it in later updates:

<pre>doServer() {
    # Turning machine into a server

    local port=${1:-&quot;&quot;}
    local description=${2:-&quot;&quot;}
    local ip=${3:-&quot;0.0.0.0&quot;}

    # Creating directory with nobody permissions
    mkdir -p &quot;/var/local/pastecat&quot;
    chmod 777 &quot;/var/local/pastecat&quot; &amp;&amp; cd &quot;/var/local/pastecat&quot;

    # Running pastecat 
    cmd='su '$PCUSER' -c &quot;{ '$PCPATH$PCPROG' -l :'$port' &gt; '$LOGFILE' 2&gt;&amp;1 &amp; }; echo \$!&quot;'
    pidpc=$(eval $cmd)          # keeping PID for future needs...

    cd -

    # Using the PID, we could carry on process control so if the pastecat process die, we can also
    # stop the avahi process to avoid &quot;false connections&quot;

    return
}</pre>
Note that we are using some global variables that were not defined before such as <code>PCUSER</code> and <code>LOGFILE</code>. By default, we set these variables like this:

<pre>PCPATH=&quot;/opt/pastecat/&quot;
PCPROG=&quot;pastecat&quot;
LOGFILE=&quot;/dev/null&quot;
PCUSER=&quot;nobody</pre>

===== Stop the service =====

Sometimes, we may also want to stop out service, so we will provide a button to do so. The first thing would be creating the button, but if we think a little, we will figure out that before doing this, we need a way to know if our service is running. In addition, we also need a way to stop our service. Since we are running on Linux, we can easily achieve that by using the <code>kill</code> command. The thing is that to use this command, we need the Process ID (PID). Luckily for us, we already kept this number when we created the pastecat server with <code>pidpc=$(eval $cmd)</code>.

Now that we have everything we need to kill our process, let's provide a way so the PHP can detect whether Pastecat is running or not. An easy and resulting way to do this is storing some useful data in a file and delete this file when pastecat is stopped. This way, we make sure that this file will only exists when Pastecat is running. This file will be created from the controller adding the following lines right below the sentence we mentioned in the previous paragraph:

<pre># Writting server info to file
info=&quot;$pidpc http://$ip:$port&quot;          # Separator is space character
echo $info &gt; $PCFILE</pre>
where <code>$PCFILE</code> is <code>/var/run/pc.info</code>. Note that the content of this file will be the PID and the complete direction of our Pastecat server.

Now we have a way to know if our server is up or down, so we can add the &quot;stop&quot; button in the web interfae. We will modify a little bit the PHP script that we had before, just by addind anther advertisement indicating whether Pastecat is up or down, and 2 more buttons if it is running. So, in our index function, within the condition that checks if Pastecat is installed we will have the following code:

<pre>$page .= &quot;&lt;div class='alert alert-success text-center'&gt;&quot;.t(&quot;Pastecat is installed&quot;).&quot;&lt;/div&gt;\n&quot;;
if ( isRunning() ) {
    $page .= &quot;&lt;div class='alert alert-success text-center'&gt;&quot;.t(&quot;Pastecat is running&quot;).&quot;&lt;/div&gt;\n&quot;;
    $page .= addButton(array('label'=&gt;t('Go to server'),'href'=&gt;'http://'. getCommunityIP()['output'][0] .':'. $port));
    $page .= addButton(array('label'=&gt;t('Stop server'),'href'=&gt;$staticFile.'/pastecat/stop'));
} else  {
    $page .= &quot;&lt;div class='alert alert-error text-center'&gt;&quot;.t(&quot;Pastecat is not running&quot;).&quot;&lt;/div&gt;\n&quot;;
}
$page .= addButton(array('label'=&gt;t('Create a Pastecat server'),'href'=&gt;$staticFile.'/pastecat/publish'));</pre>
In this piece of code, we can appreciate 2 new features in our code. The first one is a check function called <code>isRunning()</code>. This function looks very similar to the function we used to check if Pastecat is installed:

<pre>function isRunning() {
    // Returns whether pastecat is running or not
    global $pcfile;

    return(file_exists($pcfile));   
}</pre>
It is a simple as it seems, it just checks if the file we created when starting the server still exists. The second thing we can notice in the new PHP code is the existance of a new function called <code>stop</code>. This function will invoke another function in the controller which will stop the pastecat:

<pre>function stop() {
    // Stops Pastecat server
    global $pcpath,$pcprogram,$title,$pcutils,$avahi_type,$port;

    $page = &quot;&quot;;
    $cmd = $pcutils.&quot; stop &quot;;
    execute_program_detached($cmd);

    return(array('type'=&gt;'redirect','url'=&gt;$staticFile.'/pastecat'));
}</pre>
In order to make the controller understand this order, we will modify the case and add the new function. In the <code>case</code> statement, we will add the following under the <code>install</code> option:

<pre>&quot;stop&quot;)
    shift
    doStop $@
    ;;</pre>
This calls the function <code>doStop</code> within the controller. This function will look like this:

<pre>doStop() {
    # Stopping pastecat server
    pcpid=$(cat $PCFILE | cut -d' ' -f1)
    kill $pcpid

    # Removing info file
    rm $PCFILE
}</pre>
This function just gets the pastecat's PID from the file we created before, kills the process and finally removes the file so the PHP scripts can know that pastecat is now down.

Now we can create a pastecat instance server and stop it. However, there is still something missing: make the other users see our service. And this is why we are using avahi.

=== Avahi service publishing ===

On of the best things in Cloudy is the facility of publishing our service as a publication in the avahi network, allowing other users to know what we are offering and joining our service. To do this, we first need to add a few lines to the PHP controller, just after we've called the controller to start the pastecat instance. We will add the following lines:

<pre>$description = str_replace(' ', '', $description);
$temp = avahi_publish($avahi_type, $description, $port, &quot;&quot;);
$page .= ptxt($temp);</pre>
So in the end our function will look like this:

<pre>function _pcsource($port,$description) {
    global $pcpath,$pcprogram,$title,$pcutils,$avahi_type;

    $page = &quot;&quot;;
    $device = getCommunityDev()['output'][0];
    $ipserver = getCommunityIP()['output'][0];

    if ($description == &quot;&quot;) $description = $type;

    $cmd = $pcutils.&quot; publish '$port' '$description'&quot;;
    execute_program_detached($cmd);

    $page .= t($ipserver);
    $page .= par(t('Published this server.'));
    $description = str_replace(' ', '', $description);
    $temp = avahi_publish($avahi_type, $description, $port, &quot;&quot;);
    $page .= ptxt($temp);

    $page .= addButton(array('label'=&gt;t('Back'),'href'=&gt;$staticFile.'/pastecat'));

    return($page)
}</pre>
With this simple step, we announced our service in the avahi network. However the work does not end here, there is still one more thing to do: create a button and program it so when clicked, it directly goes to our pastecat server.

To do this there is a folder called <code>avahi</code> within the <code>plug</code> directory. The scripts that define the function carried on when the button is clicked are defined in different files within this directory, therefor we will create a new file called <code>pastecat.avahi.PHP</code> which will contain this:

<pre>&lt;?PHP
// plug/avahi/pastecat.avahi.PHP

addAvahi('pastecat','fpcserver');

function fpcserver($dates){
    global $staticFile;

    return (&quot;&lt;a class='btn' href='http://&quot; .$dates['ip'] .&quot;:&quot;. $dates['port'].&quot;'&gt;Go to server&lt;/a&gt;  &quot;);
}</pre>
This will create a button besides the avahi announcement line that will point to our server.

Now that we have our service announced, we want it to dissappear when we stop the pastecat service. This last step is very simple yet important. It consist of a few lines in the PHP function called stop. Until now, this function just called the controller and stopped the pastecat, but now it will also stop the avahi publication and show a flash comment so the user knwo it worked:

<pre>$temp = avahi_unpublish($avahi_type, $port);
$flash = ptxt($temp);
setFlash($flash);</pre>
These lines will be added just after the <code>execute_program_detached($cmd)</code> sentence in the stop function.

=== Final ===

Finally just comment that all the files implemented in this tutorial can be found in a Github repository, linked in the External Link section, also with this tutorial in Markdown format (md).



== References ==

<references/>



== External links ==

https://github.com/Clommunity/Doc/tree/master/plugins/pastecat



[[Category:Cloudy]]
[[ca:Cloudy_plug-ins]]
[[es:Cloudy_plug-ins]]