Guifi.net - English Wiki - User contributions [en]

Cloudy plug-ins

2015-12-03T17:23:23Z

Conxuro:

== 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_v0.3.0</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 "the controller". 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><?PHP
//peerstreamer.menu.PHP
addMenu('Pastecat','pastecat','Clommunity');</pre>
By now, we'll use a very simple PHP script in the controller:

<pre><?PHP
//pastecat
$title="Pastecat";

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

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

return(array('type' => 'render','page' => $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_v0.3.0</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="/opt/pastecat/"

doInstall() {
if isInstall
then
echo "Pastecat is already installed."
return
fi

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

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

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

cd -
}

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

case $1 in
"install")
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'=>t('Create a Pastecat server'),'href'=>$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("Write the port to publish your Pastecat service"));
$page .= createForm(array('class'=>'form-horizontal'));
$page .= addInput('description',t('Describe this server'));
$page .= addSubmit(array('label'=>t('Publish'),'class'=>'btn btn-primary'));
$page .= addButton(array('label'=>t('Cancel'),'href'=>$staticFile.'/peerstreamer'));

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

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

$page = "<pre>";
$page .= _pcsource($description);
$page .= "</pre>";

return(array('type' => 'render','page' => $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 = "";
$device = getCommunityDev()['output'][0];
$ipserver = getCommunityIP()['output'][0];

if ($description == "") $description = $type;

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

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

$page .= addButton(array('label'=>t('Back'),'href'=>$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
"install")
shift
doInstall $@
;;
"publish")
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:-""}
local description=${2:-""}
local ip=${3:-"0.0.0.0"}

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

# Running pastecat
cmd='su '$PCUSER' -c "{ '$PCPATH$PCPROG' -l :'$port' > '$LOGFILE' 2>&1 & }; echo \$!"'
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 "false connections"

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="/opt/pastecat/"
PCPROG="pastecat"
LOGFILE="/dev/null"
PCUSER="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="$pidpc http://$ip:$port" # Separator is space character
echo $info > $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 "stop" 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 .= "<div class='alert alert-success text-center'>".t("Pastecat is installed")."</div>\n";
if ( isRunning() ) {
$page .= "<div class='alert alert-success text-center'>".t("Pastecat is running")."</div>\n";
$page .= addButton(array('label'=>t('Go to server'),'href'=>'http://'. getCommunityIP()['output'][0] .':'. $port));
$page .= addButton(array('label'=>t('Stop server'),'href'=>$staticFile.'/pastecat/stop'));
} else {
$page .= "<div class='alert alert-error text-center'>".t("Pastecat is not running")."</div>\n";
}
$page .= addButton(array('label'=>t('Create a Pastecat server'),'href'=>$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 = "";
$cmd = $pcutils." stop ";
execute_program_detached($cmd);

return(array('type'=>'redirect','url'=>$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>"stop")
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, "");
$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 = "";
$device = getCommunityDev()['output'][0];
$ipserver = getCommunityIP()['output'][0];

if ($description == "") $description = $type;

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

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

$page .= addButton(array('label'=>t('Back'),'href'=>$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><?PHP
// plug/avahi/pastecat.avahi.PHP

addAvahi('pastecat','fpcserver');

function fpcserver($dates){
global $staticFile;

return ("<a class='btn' href='http://" .$dates['ip'] .":". $dates['port']."'>Go to server</a> ");
}</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]]

Cloudy web UI

2015-12-03T17:14:32Z

Conxuro:

== Introduction ==

The Cloudy web User Interface (UI) uses an application called cDistro <ref name="cdistro">cDistro git repository: https://github.com/Clommunity/cDistro</ref>.

''(Add what it is)''

== Configuration ==

The cDistro configuration is placed in <s>/etc/cdistro.conf</s> /etc/cloudy/cloudy.conf

By default it has the following format:

#cdistro config
SERVER="/usr/bin/php"
OPTS=""
BINDIP="0.0.0.0"
PORT="7000"
DOCROOT="/var/local/cDistro"
# SSHAUTH=1 <- check user with ssh2 connection http://www.php.net/manual/en/function.ssh2-auth-password.php (Require: libssh2-php)
SSHAUTH=1
# LOGIN="root"
## PASSWORD = md5(md5('secret')) => php -r 'echo md5(md5("secret"))."\n";'
#PASSWORD="7022cd14c42ff272619d6beacdc9ffde"
PORT_SSL=7443

=== SERVER ===

The path of the PHP executable.

'''Example:'''

* "/usr/bin/php" - in the case of Cloudy (Debian).

=== OPTS ===

PHP options.

''(Add references or more info and an example)''

=== BINDIP ===

The IP address where the service will be listening.

'''Example:'''

* "127.0.0.1" - will accept only petitions from localhost.
* "0.0.0.0" - will accept petitions from any address.

=== PORT ===

The port opened by the service to listen to requests.

'''Example:'''

* "7000" - opens the port 7000.

=== DOCROOT ===

The path of the cDistro application.

'''Example:'''

* "/var/local/cDistro" - in the case of Cloudy.

=== SSLAUTH ===

Parameter that allows authentication via SSH2 in the application, i.e., to use the credentials that the SSH server of the system allows.

Can be 0 or 1.

'''Example:'''

* "1" - actives this option.
* "0" - disables this option (will require to define user and password).

=== LOGIN ===

The username to authenticate against the application.

Should be a string without spaces.

'''Example:'''

* "cloudy" - this user can log-in with the password of PASSWORD.

=== PASSWORD ===

The password of the user defined in LOGIN.

Should be a hash over a hash MD5 (hexadecimal), i.e., a hash of the password hash: md5(md5("PASSWORD")).

'''Example:'''

* "46d934e0f59ff1e2272f9f5f7950e5d9" - the hash of the string "PASSWORD".

'''Examples of how to generate that hash in a terminal:'''

$ php -r 'echo md5(md5("PASSWORD"))."\n";'
46d934e0f59ff1e2272f9f5f7950e5d9
$ printf "PASSWORD" | md5sum | awk '{printf $1}' | md5sum | awk '{print $1}'
46d934e0f59ff1e2272f9f5f7950e5d9

=== PORT_SSL ===

Port that Cloudy will use in the web interface with HTTPS (if SSL is enabled).

'''Example:'''

* "7443" - access to the web interface in https://IP_SERVIDOR:7443.

== References ==

<references/>

[[Category:Cloudy]]

Cloudy packages repository

2015-09-15T16:44:15Z

Conxuro: Created page with "'''''Note: this article may be outdated and should be revised. Be careful if you try to follow this guide, and better if you ask in the mailing lists first.''''' == Upload ..."

'''''Note: this article may be outdated and should be revised. Be careful if you try to follow this guide, and better if you ask in the mailing lists first.'''''

== Upload packages to Cloudy software repository (Clommunity project) ==

We are ready to upload packages to the Cloudy public repository http://repo.clommunity-project.eu.

Here we request public keys to allow to upload packages and sign them. You can for sure, edit the scripts and change the paths to your needs.

The repository is auto-signed now with a repository key name "gcodis Distro Development Team", more info in the repository itself: http://repo.clommunity-project.eu. Auto-signing prevents that the repository remain not signed if anyone uploads unsigned packages. One signature for the repository, which is added in the client side to allow the installation of the distro, and another signature which depends on the maintainer or developer for signing the package are used. Each developer is responsible to maintain her keys safe.

=== Public keys ===

To upload packages we need to get '''your''' public keys:

* The '''ID of the GPG public key, uploaded to gpg.mit.edu'''. With this key you will sign the uploads.
* The '''public SSH key''', to access to upload packages. Needed to access to the remote repository machine.

The packages are uploaded to the unstable branch by default (use the package changelog for that). We use the <code>dput</code> Debian tool to upload packages and sign them. The repository is auto-signed with another key.

You can '''send''' the public keys or IDs to the project mailing list ''clommunity-wp4''. This way we have access to public keys when required.

=== Files ===

The provided configuration file is:

* <code>.dput.cf</code> is a configuration file which have to be copied to your home directory as <code>~/.dput.cf</code>. Used for uploading packages with the <code>dput</code> Debian tool.

<code>
[repo.clommunity-project.eu]
fqdn = repo.clommunity-project.eu
method = scp
login = repo
incoming = /var/www/debian/mini-dinstall/incoming
post_upload_command = ssh repo@repo.clommunity-project.eu "mini-dinstall -b"
</code>

=== Building packages ===

Take a look to some manners to build packages at http://www.debian.org/doc/manuals/maint-guide/build.en.html.

=== Uploading packages ===

You can use the <code>dput</code> command in the following manner:

<code>
$ dput repo.clommunity-project.eu cloudy-base_0.1.3.5_i386.changes
</code>

Remember to save the previous <code>~/.dput.cf</code> file in your <code>$HOME</code> dir.

It's important to write the repository name ''(repo.clommunity-project.eu)''.

=== Continuous improvements ===

The repository is improving to better working when needed to give a better service.

Thank you by your efforts.

[[Category:Cloudy]]

Cloudy Alix

2015-09-11T02:32:29Z

Conxuro: Created page with "Alix is a [https://en.wikipedia.org/wiki/Single-board_computer SBC] with an AMD (x86) processor and several input-output interfaces (serial, miniPCI, Ethernet, etc.). For that..."

Alix is a [https://en.wikipedia.org/wiki/Single-board_computer SBC] with an AMD (x86) processor and several input-output interfaces (serial, miniPCI, Ethernet, etc.). For that reason is needed an operative system prepared to run with the corresponding drivers to make these interfaces work.

''Note: this guide has been done with Debian specially prepared to work on Alix, but it is possible that with similar steps it work with another Debian based distribution.''

== Get Debian for Alix ==

You can [https://code.google.com/p/debian-for-alix/ download at this website] a special Debian images just ready to work in Alix boards after flashing them in a CF card.

=== Features/services included ===

* Read only file system, it protects against power failures and substantially increases compact flash life time.

* Common services available on first boot:
** serial terminal ( 38400n8 )
** dnsmasq ( DNS and DHCP servers )
** iptables ( basic firewall rules and internet sharing )
** samba ( Microsoft Windows file share )
** cups ( print server )
** vsftpd ( FTP server )
** nginx with fastcgi ( HTTP server )
** minidlna ( media server )
** openssh ( terminal and SFTP )
** stunnel ( SSL engine, HTTPS support pre-configured for ''nginx'' and ''transmission'' )
** tinyproxy ( HTTP/HTTPS proxy server )
** pptpd ( VPN server, MS Windows has builtin client support )
** snmpd ( SNMP server )
** openvpn ( VPN server and client )
** openconnect ( VPN client, Cisco compatible )
** external storage automount and sharing basic web admin panel performance monitor ( on web panel )

* Additional services available:
** just turned on transmission ( torrent p2p )
** hostapd ( wireless access point / it needs a miniPCI card or wifi usb dongle )

* Regular system maintenance through <code>apt-get</code>, use it to update, install and remove applications and patches.

* Keep in mind that it's a Debian i386, so any available software for that platform can be installed, regards hardware power limitations.

* Image files are available for download at GoogleDrive:
** debian-for-alix-v1.img.bz2 (debian 6 based) version 1 wiki page
** debian-for-alix-v2.img.bz2 (debian 6 based) version 2 wiki page
** debian-for-alix-v3.img.bz2 (debian 7 based) Debian basic setup, only SSH server and basic utilities, also serial terminal was prepared, but no readonly file system and other features.

* Default configuration is:
<code>eth0: DHCP</code>

<code>eth1: static 172.16.210.254</code>

<code>eth2: no configuration</code>

<code>user: alix (root has locked password)</code>

== Install Debian image on CF ==

=== Identify the CF ===

The CF card need to be formatted with ext2. Be sure what device your CF card is, otherwise you could erase your host OS. In this example the CF card was on <code>/dev/sdb</code>.

You can check it out having a look through the <code>/proc/bus/usb/devices</code>. You should see a section with an ''S:'' line and the name of your reader, and an ''I:'' line with <code>Driver=usb-storage</code>. If you see that, the kernel is recognizing the device.

Install the <code>sg3-utils</code> package if you haven't already it (on Debian: <code>apt-get install sg3-utils</code>). To check your SCSI devices, run the command:
sg_scan -i

You should see something like this:
/dev/sg0: scsi0 channel=0 id=0 lun=0 [em] type=0
eUSB Compact Flash 5.09 [wide=0 sync=0 cmdq=0 sftre=0 pq=0x0]

It indicates that the “raw” SCSI device associated with your reader is <code>/dev/sg0</code>. You can also confirm that the driver is working by looking at the file <code>/proc/scsi/scsi</code>. Now, to determine the real SCSI device associated with your reader run the command:
sg_map

You'll see output like this:
/dev/sg0 /dev/sdb

That's it, your card reader is <code>/dev/sdb</code>. The first (and almost certainly only) partition is <code>/dev/sdb1</code>.

=== Copy image to CF ===

To install Debian on the CF card you can do it with the following command:
bzcat debian-for-alix-v3.img.bz2 | dd of=/dev/sdb bs=16k

== Install Cloudy ==

To install Cloudy you can follow the instructions to [[Cloudy_in_Debian|convert a plain Debian installation in Cloudy]] by adding the system the specific files and tools of the distribution.

We call it "cloudynize".

We recommend to use a script to automate the process. You can know how to in the [[cloudynize|wiki page that explains how to "cloudynize"]].

[[Category:Cloudy]]

Cloudy Beaglebone

2015-09-10T20:20:45Z

Conxuro: Created page with "Beaglebone is a [https://en.wikipedia.org/wiki/Single-board_computer SBC] with an ARM processor and several input-output interfaces. For that reason is needed an operative sys..."

Beaglebone is a [https://en.wikipedia.org/wiki/Single-board_computer SBC] with an ARM processor and several input-output interfaces. For that reason is needed an operative system prepared to run on an ARM architecture and with the corresponding drivers to make these interfaces work.

''Note: this guide has been done with Ubuntu distribution, but it is possible that with the same steps it work with another Debian based distribution.''

== Install the base system ==

* Insert the microSD Card into your computer and observe which device it registers as by typing ls /dev/sd. If you are uncertain, remove the microSD Card and the entry should go away. Once you know which device your microSD Card is, follow the instructions below replacing /dev/sdX with the name of the microSD Card in your system.

* Begin partitioning the microSD card by typing <code>fdisk /dev/sdX</code>.
# Initialize a new partition table by selecting <code>o</code>, then verify is empty by selecting <code>p</code>.
# Create a boot partition by selecting <code>n</code> ''(new)'', then <code>p</code> ''(primary)'', and <code>1</code> to specify the first partition. Press ''enter'' to accept the default first sector and specify <code>4095</code> for the last sector.
# Change the partition type to FAT16 by selecting <code>t</code> ''(type)'' and <code>e</code> for ''‘W95 FAT16 (LBA)’''.
# Set the partition bootable by selecting <code>a</code> then <code>1</code>.
# Next, create the data partition for the root filesystem by selecting <code>n</code> for ''(new)'', then <code>p</code> ''(primary)'', and <code>2</code> to specify the second partition. Accept the default values for the first and last sectors by pressing ''enter'' twice.
# Press <code>p</code> to ‘print’ the partition table.
# Finally, commit the changes by selecting <code>w</code> to ''write'' the partition table and exit ''fdisk''.

* Continue to format the partitions and to install the boot system and the root system.
# Format partition 1 as FAT by typing <code>mkfs.vfat /dev/sdX1</code>.
# Format partition 2 as ext4 by typing <code>mkfs.ext4 /dev/sdX2</code>.
# Install ''u-boot'' to the microSD Card.
wget http://s3.armhf.com/dist/bone/bone-uboot.tar.xz
mkdir boot
mount /dev/sdX1 boot
tar xJvf bone-uboot.tar.xz -C boot
umount boot
# Install the desired root filesystem to the microSD card (Ubuntu Trusty in this example).
wget http://s3.armhf.com/dist/bone/ubuntu-trusty-14.04-rootfs-3.14.4.1-bone-armhf.com.tar.xz
mkdir rootfs
mount /dev/sdX2 rootfs
tar xJvf ubuntu-trusty-14.04-rootfs-3.14.4.1-bone-armhf.com.tar.xz -C rootfs
umount rootfs

The microSD Card is now ready to boot. Note that for ubuntu installations, the login userid is ''ubuntu'' and the password is ''ubuntu''.

''Tip: the package cache has been flushed to reduce the size of the images. Run <code>apt-get update</code> after boot to update the package cache, then run <code>apt-get upgrade</code> to ensure the latest updates are installed.''

== Install Cloudy ==

To install Cloudy you can follow the instructions to [[Cloudy_in_Debian|convert a plain Debian installation in Cloudy]] by adding the system the specific files and tools of the distribution.

We call it "cloudynize".

We recommend to use a script to automate the process. You can know how to in the [[cloudynize|wiki page that explains how to "cloudynize"]].

[[Category:Cloudy]]

Cloudy Raspberry Pi

2015-09-10T18:00:16Z

Conxuro:

The Raspberry Pi is a tiny and affordable computer as large as a credit card, made mainly to be used for educational purposes and in small projects.

This board has an ARM processor and several input-output interfaces; video, sound, Ethernet, USB, GPIO, etc. For that reason is needed an operative system prepared to run on an ARM architecture and with the corresponding drivers to make these interfaces work.

In our case, to install Cloudy, the Raspberry Pi will be prepared with an already adapted distribution based in Debian like it's Raspbian, and once it is done we will "cloudynize" it to add all the particular content of Cloudy.

'''''Note:''' this guide, as well as the different Cloudy installation tests, has been done with the Raspbian O.S.; but it is possible that with the same steps it work with another Debian based distribution.''

== Download Raspbian ==

Go to the [https://www.raspberrypi.org/downloads/ official website] and download the ISO image with the operating system you will use as a base.

Alternatively a Raspbian variant can be used, the [http://sirlagz.net/2013/07/19/raspbian-server-edition-2-5/ Raspbian Server Edition], which is already prepared without the unneeded packages (graphical system, sound, etc.) in the use of the Raspberry Pi as a server.

== Install and configure Raspbian ==

Write the image in an SD card. Depending on the operating system of your PC you can follow one of these guides to write ISO images.

* [http://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux]
* [http://www.raspberrypi.org/documentation/installation/installing-images/mac.md Mac OS]
* [http://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]

Now insert the card and power on the board to start the configuration process with the <code>raspi-config</code> tool.

Basically it's recommended to do:
# Expand the file system to use the whole SD storage space.
# Change the password of the '''pi''' user (the system default one).
# Change the localization if another language is wanted, the timezone and the keyboard layout.
# In the advanced options; enable the SSH server, change the hostname and update the <code>raspi-config</code>.

If you want to do some more changes, you can find more information in the [https://www.raspberrypi.org/documentation/configuration/raspi-config.md raspi-config documentation].

We won't extend more to explain how to install and to configure Raspbian because is widely documented in the Web.

=== Additional options ===

As it's commented above, there is a variant of Raspbian customized to work as a server, deleting all the unneeded packages. This version should work like the original Raspbian, but it's recommended to adapt the system just after the installation manually or automating it with the ''script'' that uninstalls the packages to leave the system like the Rasbian Server Edition.

You can find more info and download that script at [http://sirlagz.net/2013/08/03/raspbian-server-edition-scripts/ this website].

== Install Cloudy ==

To install Cloudy you can follow the instructions to [[Cloudy_en_Debian|convert a plain Debian installation in Cloudy]] by adding the system the specific files and tools of the distribution.

We call it "cloudynize".

We recommend to use a script to automate the process. You can know how to in the [[cloudynize|wiki page that explains how to "cloudynize"]].

[[Category:Cloudy]]

Cloudy Raspberry Pi

2015-09-10T17:56:33Z

Conxuro:

The Raspberry Pi is a tiny and affordable computer as large as a credit card, made mainly to be used for educational purposes and in small projects.

This board has an ARM processor and several input-output interfaces; video, sound, Ethernet, USB, GPIO, etc. For that reason is needed an operative system prepared to run on an ARM architecture and with the corresponding drivers to make these interfaces work.

In our case, to install Cloudy, the Raspberry Pi will be prepared with an already adapted distribution based in Debian like it's Raspbian, and once it is done we will "cloudynize" it to add all the particular content of Cloudy.

'''''Note:''' this guide, as well as the different Cloudy installation tests, has been done with the Raspbian O.S.; but it is possible that with the same steps it work with another Debian based distribution.''

== Download Raspbian ==

Go to the [https://www.raspberrypi.org/downloads/ official website] and download the ISO image with the operating system you will use as a base.

Alternatively a Raspbian variant can be used, the [http://sirlagz.net/2013/07/19/raspbian-server-edition-2-5/ Raspbian Server Edition], which is already prepared without the unneeded packages (graphical system, sound, etc.) in the use of the Raspberry Pi as a server.

== Install and configure Raspbian ==

Write the image in an SD card. Depending on the operating system of your PC you can follow one of these guides to write ISO images.

* [http://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux]
* [http://www.raspberrypi.org/documentation/installation/installing-images/mac.md Mac OS]
* [http://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]

Now insert the card and power on the board to start the configuration process with the <code>raspi-config</code> tool.

Basically it's recommended to do:
# Expand the file system to use the whole SD storage space.
# Change the password of the '''pi''' user (the system default one).
# Change the localization if another language is wanted, the timezone and the keyboard layout.
# In the advanced options; enable the SSH server, change the hostname and update the <code>raspi-config</code>.

If you want to do some more changes, you can find more information in the [https://www.raspberrypi.org/documentation/configuration/raspi-config.md raspi-config documentation].

We won't extend more to explain how to install and to configure Raspbian because is widely documented in the Web.

=== Additional options ===

As it's commented above, there is a variant of Raspbian customized to work as a server, deleting all the unneeded packages. This version should work like the original Raspbian, but it's recommended to adapt the system just after the installation manually or automating it with the ''script'' that uninstalls the packages to leave the system like the Rasbian Server Edition.

You can find more info and download that script at [http://sirlagz.net/2013/08/03/raspbian-server-edition-scripts/ this website].

== Install Cloudy ==

To install Cloudy you can follow the instructions to [[Cloudy_en_Debian|convert a plain Debian installation in Cloudy]] by adding the system the specific files and tools of the Cloudy distribution.

We call it "cloudynize".

We recommend to use a script to automate the process, you can know how to in the [[cloudynize|wiki page that explains how to cloudynize]].

[[Category:Cloudy]]

Cloudy in Debian

2015-09-10T17:41:39Z

Conxuro:

You can convert a plain Debian installation into Cloudy following these steps:

1. Enter via SSH as a root user (or once logged in) or execute the next commands with ''sudo'' tool.

2. Update date from server by installing a NTP client ''(optional)''.

apt-get install ntp

3. Add Debian backports, Clommunity and Guifi repositories.
* Debian backports:
echo "deb http://ftp.debian.org/debian wheezy-backports main contrib" > /etc/apt/sources.list.d/backports.list
* Clommunity repository:
echo "deb http://repo.clommunity-project.eu/debian unstable/" > /etc/apt/sources.list.d/cloudy.list
gpg --keyserver pgpkeys.mit.edu --recv-key A59C5DC8 && gpg --export --armor A59C5DC8 | apt-key add -
* Guifi repository:
echo "deb http://serveis.guifi.net/debian guifi/" > /etc/apt/sources.list.d/serveis.list
gpg --keyserver pgpkeys.mit.edu --recv-key 2E484DAB && gpg --export --armor 2E484DAB | apt-key add -

4. Install some Debian packages.
apt-get update
apt-get upgrade
apt-get install -y openssh-server openssh-client getinconf-client curl unzip make avahi-utils tahoe-lafs mysql-server python2.7 g++ make checkinstall openjdk-6-jre locales php5 libssh2-php libapache2-mod-encoding

'''''Note''': If this error appears: "Error W: GPG error: http://ftp.debian.org wheezy-backports InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY8B48AD6246925553" use this command:
apt-get --allow-unauthenticated upgrade
''

5. Install the Cloudy non-Debian packages.
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/getinconf-client.chroot" | sh -
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/avahi-ps.chroot" | sh -
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/cDistro.chroot" | sh -

g. Reboot.

After this, you can browse the web user interface at http://device_IP:7000

[[Category:Cloudy]]

Cloudy in Debian

2015-09-10T17:33:26Z

Conxuro:

You can convert a plain Debian installation into Cloudy following these steps:

1. Enter via SSH as a root user (or once logged in) or execute the next commands with ''sudo'' tool.

2. Update date from server by installing a ntp client ''(optional)''.

apt-get install ntp

3. Add Debian backports, Clommunity and Guifi repositories.
* Debian Backports:
echo "deb http://ftp.debian.org/debian wheezy-backports main contrib" > /etc/apt/sources.list.d/backports.list
* Clommunity repository
echo "deb http://repo.clommunity-project.eu/debian unstable/" > /etc/apt/sources.list.d/cloudy.list
gpg --keyserver pgpkeys.mit.edu --recv-key A59C5DC8 && gpg --export --armor A59C5DC8 | apt-key add -
* Guifi repository
echo "deb http://serveis.guifi.net/debian guifi/" > /etc/apt/sources.list.d/serveis.list
gpg --keyserver pgpkeys.mit.edu --recv-key 2E484DAB && gpg --export --armor 2E484DAB | apt-key add -

4. Install some Debian packages.
apt-get update
apt-get upgrade
apt-get install -y openssh-server openssh-client getinconf-client curl unzip make avahi-utils tahoe-lafs mysql-server python2.7 g++ make checkinstall openjdk-6-jre locales php5 libssh2-php libapache2-mod-encoding

'''''Note''': If this error appears: ·Error W: GPG error: http://ftp.debian.org wheezy-backports InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY8B48AD6246925553" use this command:
apt-get --allow-unauthenticated upgrade
''

5. Install the Cloudy non-Debian packages.
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/getinconf-client.chroot" | sh -
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/avahi-ps.chroot" | sh -
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/cDistro.chroot" | sh -

g. Reboot.

After this, you can browse the web user interface at http://device_IP:7000

[[Category:Cloudy]]

Cloudy in Debian

2015-09-10T17:32:40Z

Conxuro: Created page with "You can convert a plain Debian installation into Cloudy following these steps: 1. Enter via SSH as a root user (or once logged in) or execute the next commands with ''sudo''..."

You can convert a plain Debian installation into Cloudy following these steps:

1. Enter via SSH as a root user (or once logged in) or execute the next commands with ''sudo'' tool.

2. Update date from server by installing a ntp client (optional).

apt-get install ntp

3. Add Debian backports, Clommunity and Guifi repositories.
* Debian Backports:
echo "deb http://ftp.debian.org/debian wheezy-backports main contrib" > /etc/apt/sources.list.d/backports.list
* Clommunity repository
echo "deb http://repo.clommunity-project.eu/debian unstable/" > /etc/apt/sources.list.d/cloudy.list
gpg --keyserver pgpkeys.mit.edu --recv-key A59C5DC8 && gpg --export --armor A59C5DC8 | apt-key add -
* Guifi repository
echo "deb http://serveis.guifi.net/debian guifi/" > /etc/apt/sources.list.d/serveis.list
gpg --keyserver pgpkeys.mit.edu --recv-key 2E484DAB && gpg --export --armor 2E484DAB | apt-key add -

4. Install some Debian packages.
apt-get update
apt-get upgrade
apt-get install -y openssh-server openssh-client getinconf-client curl unzip make avahi-utils tahoe-lafs mysql-server python2.7 g++ make checkinstall openjdk-6-jre locales php5 libssh2-php libapache2-mod-encoding

'''''Note''': If this error appears: ·Error W: GPG error: http://ftp.debian.org wheezy-backports InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY8B48AD6246925553" use this command:
apt-get --allow-unauthenticated upgrade
''

5. Install non-Debian packages.
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/getinconf-client.chroot" | sh -
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/avahi-ps.chroot" | sh -
curl "https://raw.githubusercontent.com/Clommunity/lbmake/master/hooks/cDistro.chroot" | sh -

g. Reboot.

After this, you can browse the web user interface at http://device_IP:7000

[[Category:Cloudy]]

Cloudy Raspberry PI

2015-07-22T01:00:21Z

Conxuro: Redirected page to Cloudy Raspberry Pi

#REDIRECT [[Cloudy_Raspberry_Pi]]

Cloudy Raspberry Pi

2015-07-22T00:30:26Z

Conxuro: Created page with "The Raspberry Pi is a tiny and affordable computer as large as a credit card, made mainly to be used for educational purposes and in small projects. This board has an ARM pro..."

The Raspberry Pi is a tiny and affordable computer as large as a credit card, made mainly to be used for educational purposes and in small projects.

This board has an ARM processor and several input-output interfaces; video, sound, Ethernet, USB, GPIO, etc. For that reason is needed an operative system prepared to run on an ARM architecture and with the corresponding drivers to make these interfaces work.

In our case, to install Cloudy, the Raspberry Pi will be prepared with an already adapted distribution based in Debian like it's Raspbian, and once it is done we will "cloudynize" it to add all the particular content of Cloudy.

'''''Note:''' this guide, as well as the different Cloudy installation tests, has been done with the Raspbian O.S.; but it is possible that with the same steps it work with another Debian based distribution.''

== Download Raspbian ==

Go to the [https://www.raspberrypi.org/downloads/ official website] and download the ISO image with the operating system you will use as a base.

Alternatively a Raspbian variant can be used, the [http://sirlagz.net/2013/07/19/raspbian-server-edition-2-5/ Raspbian Server Edition], which is already prepared without the unneeded packages (graphical system, sound, etc.) in the use of the Raspberry Pi as a server.

== Install and configure Raspbian ==

Write the image in an SD card. Depending on the operating system of your PC you can follow one of these guides to write ISO images.

* [http://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux]
* [http://www.raspberrypi.org/documentation/installation/installing-images/mac.md Mac OS]
* [http://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]

Now insert the card and power on the board to start the configuration process with the <code>raspi-config</code> tool.

Basically it's recommended to do:
# Expand the file system to use the whole SD storage space.
# Change the password of the '''pi''' user (the system default one).
# Change the localization if another language is wanted, the timezone and the keyboard layout.
# In the advanced options; enable the SSH server, change the hostname and update the <code>raspi-config</code>.

If you want to do some more changes, you can find more information in the [https://www.raspberrypi.org/documentation/configuration/raspi-config.md raspi-config documentation].

We won't extend more to explain how to install and to configure Raspbian because is widely documented in the Web.

=== Additional options ===

As it's commented above, there is a variant of Raspbian customized to work as a server, deleting all the unneeded packages. This version should work like the original Raspbian, but it's recommended to adapt the system just after the installation manually or automating it with the ''script'' that uninstalls the packages to leave the system like the Rasbian Server Edition.

You can find more info and download that script at [http://sirlagz.net/2013/08/03/raspbian-server-edition-scripts/ this website].

== Install Cloudy ==

To install Cloudy we "cloudynize" the system to add it the specific files and tools of the Cloudy distribution.

To do it, you can follow the instructions of the [[cloudynize|wiki page that explains how to cloudynize a Debian system]].

[[Category:Cloudy]]

Cloudy in client node

2015-07-17T15:57:59Z

Conxuro: Created page with "Cloudy uses a system to publish and search services, to share them with the other Cloudys. For this purpose, actually [https://www.serfdom.io/ Serf] is used. This software op..."

Cloudy uses a system to publish and search services, to share them with the other Cloudys. For this purpose, actually [https://www.serfdom.io/ Serf] is used.

This software opens a TCP port in the server (Cloudy) to listen to petitions and to be able to communicate to others.

Therefore, some additional steps are needed to allow a Cloudy installed in a client node to interact to other Cloudys:

1. Know the node’s public IP address (10.x.x.x); not the one assigned to Cloudy but the IP assigned to the client node.
* You can go to the [http://guifi.net Guifi] page of your node to know what is its IP.

2. Edit a couple of files and declare the public IP of the node. You have to add the IP in the configuration files in order to allow the software to announce correctly the public IP instead the private IP.
* To do it, with the '''''root''''' user, write in the command line the following:
<pre>
root@cloudy:~# echo "ADVERTISE_IP=10.x.x.x" >> /etc/avahi-ps-serf.conf
root@cloudy:~# echo "PUBLIC_IP=10.x.x.x" >> /etc/getinconf-client.conf
root@cloudy:~# /etc/init.d/serf restart

(where 10.x.x.x is the public IP of your node)
</pre>

'''Exemple:'''
in a node with IP address 10.1.2.3 the files should be like this:
<pre>
/etc/avahi-ps-serf.conf
SERF_RPC_ADDR=127.0.0.1:7373
SERF_BIND=5000
SERF_JOIN=10.139.40.82:5000
ADVERTISE_IP=10.1.2.3

/etc/getinconf-client.conf
#!/bin/sh
# Automatically generate file
GTC_SERVER_URL=http://10.139.40.84/index.php
NETWORK_NAME=demo
NETWORK_KEY=demo
INTERNAL_DEV=eth0
# PORT=665
# GETINCONF_IGNORE=1
GETINCONF_IGNORE=1
PUBLIC_IP=10.1.2.3
</pre>

3. Do a port forwarding for the port 5000 (Serf). And if you want more services you will have to redirect (forward) the port of each service.
* The configuration to do that depends on the device you have.

[[Category:Cloudy]]

Cloudy 64bits

2015-05-13T13:52:05Z

Conxuro:

Actually it is only available the 32 bits version, however you can create the 64 bits version by following these steps:

First, download the generation system (or image builder):

<pre>
apt-get install build-essential live-build imagemagick curl debootstrap git unzip
git clone http://dev.cloudy.community/guifi.net/cloudy-image-builder.git
</pre>

Now you have to do a little modification to the Makefile file:

<pre>
ARCH ?= amd64
FLAVOUR ?= amd64
</pre>

Finally, you can build the image with this command:

<pre>sudo make</pre>

Once the image has been created, you have a 64 bits version of Cloudy in ./devel/binary.hybrid.iso

----

Otherwise you can "Cloudynize" a 64 bits Debian or Debian based system to turn it into Cloudy.

Read how to in the [[Cloudynize]] wiki page.

[[Category:Cloudy]]

Cloudynize

2015-05-13T12:56:27Z

Conxuro: Created page with "An alternative method to install Cloudy is modifying a Debian GNU/Linux system, or a Debian based, by applying a script which turns the system into a Cloudy. To do this you c..."

An alternative method to install Cloudy is modifying a Debian GNU/Linux system, or a Debian based, by applying a script which turns the system into a Cloudy.

To do this you can run the following commands:

<pre>
git clone https://github.com/Clommunity/cloudynitzar && cd cloudynitzar
chmod +x cloudynitzar.sh
sudo ./cloudynitzar
</pre>

[[Category:Cloudy]]

Cloudy 64bits

2015-05-13T12:44:23Z

Conxuro:

Cloudy 64bits

2015-05-13T12:44:13Z

Conxuro: Created page with "Actually it is only available the 32 bits version, however you can create the 64 bits version by following these steps: First, download the generation system (or image builde..."

What is Cloudy

2015-05-13T12:25:35Z

Conxuro:

What is Cloudy

2015-05-12T20:08:28Z

Conxuro: Created page with "100px 100px Cloudy <ref name="cloudy">Cloudy: http://wiki.clommunity-project.eu/soft:cloudservices</ref> is a..."

[[File:clommunity-logo.png|right|100px]]
[[File:Logo_guifi.svg|right|100px]]

Cloudy <ref name="cloudy">Cloudy: http://wiki.clommunity-project.eu/soft:cloudservices</ref> is a distribution based in Debian GNU/Linux <ref name="debian">Debian GNU/Linux: http://debian.org</ref> developed under the CLOMMUNITY european research project.<ref name="clommunity">CLOMMUNITY project: http://clommunity-project.eu</ref>

This distribution, inspired in the idea of the old [[Guinux]] <ref name="guinux">Guinux: http://guifi.net/node/29320</ref>, facilitates the deployment and the management of cloud services<ref name="cloud-services">Cloud computing: http://en.wikipedia.org/wiki/Cloud_computing</ref>, as well as sharing them. Particulary intended to the community network<ref name="CN">Community networks: http://en.wikipedia.org/wiki/Community_network</ref> users.

----

== Introduction ==

Prior to the general adoption of cloud services<ref name="cloud-services"/>, users of Community Networks (CNs<ref name="CN"/>) already shared or provided services and resources to the community, however, these users were only a minority. One of the reasons identified is the technological barrier. Before providing content, users willing to share information with the community have first to take care of the technical aspects such as the deployment of a server with a set of services.

In the past, users from the Guifi.net CN tried to overcome this problem by releasing a GNU/Linux distribution named [[Guinux]] <ref name="guinux"/>, which provided end users an easy way of offering network services to the community (like [[Proxy_Server|HTTP proxy]], [[DNS_Server|DNS systems]] and [[Graphserver_1|MRTG graphic interfaces]]).

The key part of the distribution was a set of scripts<ref>http://en.wikipedia.org/wiki/Scripting_language</ref> that automatised the configuration process. End users were only asked for a few parameters such as their e-mail address and the node identifier. Shortly after the distribution was made available the number of end users sharing resources proliferated.

According to that, it became clear that lowering (or removing) the technological entry barrier encouraged users to provide more services and share their resources with the community. To this end, one of the goals of the CLOMMUNITY <ref name="clommunity"/> project is to release a GNU/Linux distribution, codenamed Cloudy, aimed at end users, to foster the transition and adoption of the Community Network cloud environment.

=== Motivation ===

The Cloudy distributión is thought to satisfy the following requirements:

# '''Distribution''': in order to foster services distribution amongst the Community Networks (CNs), a platform to publish and discover them is required. This way, service access does not depend on static networking deployments and is aware of the dynamically-changing conditions of CNs. The software chosen for service publishing and discovering is Avahi<ref name="avahi">Avahi: http://avahi.org</ref>.
# '''Decentralisation''': a common network layer is required to allow all CN cloud nodes to communicate with each other directly. A good way to build it is to create a virtual Layer 2 based on a VPN<ref>Virtual Private Network: http://en.wikipedia.org/wiki/Virtual_private_network</ref> service. Among the available options, Tinc VPN<ref>Tinc VPN: http://tinc-vpn.org</ref> has been chosen, as it fulfills all the requirements while being easy to configure and manage.
To coordinate the devices with TincVPN, a tool to automate the system deployment has been developed as part of the project. This software, named Getinconf<ref>Getinconf: https://github.com/Clommunity/getinconf/blob/master/README.md</ref>, takes care of the TincVPN configuration process and the exchange of keys with the rest of the cloud nodes.
# '''User-friendliness''': to this end, a web-based management platform has been developed aimed to integrate all the installation and configuration steps for the cloud services enabled in the Cloudy distribution. A simple web interface<ref>Cloudy web interface: http://redmine.confine-project.eu/projects/getinconf</ref> is available to the end user as an easy way of configure, administer and monitor the cloud services running in the node.
# '''Free, Libre, Open Source Software''': the distribution has been based on Debian GNU/Linux<ref name="debian"/>. Apart from being one of the most popular distributions and fulfilling all the technical requirements, it has been chosen because the Debian Social Contract<ref>Debian social contract: https://www.debian.org/social_contract</ref> safeguards and guarantees that the software will always be open and free.

== Minimum requirements ==

As Cloudy is based in Debian, it has the same hardware requirements.<ref>Minimum requirements: https://www.debian.org/releases/stable/i386/ch03s04.html.en</ref>

The binary image have a set of configurations and additional packages; thus are needed arround '''450 MiB of free storage space'''.
Anyway, it is '''recommended''' to have '''at least 1 GiB'''.

If you want to use some services like PeerStreamer (read below) the minimum requirements will increase, both storage, memory and processing.

== Getting Cloudy ==

Actually you can obtain the Cloudy distribution by downloading an ISO image ready to burn in a CD or USB memory, or by downloading a template (LXC container<ref>Linux containers (LXC): https://linuxcontainers.org/</ref> or OpenVZ<ref>http://openvz.org</ref>) ready to be executed in a virtual machine.

Alternatively you can download the source code and compile it by your own.

=== Downloading the image ===

Go to the Cloudy site where image are stored:

http://repo.clommunity-project.eu/images/

Currently is in development and is '''only available the ''unstable'' branch'''.

There you will find:

* cloudy.README - List of additional packages included in the image.
* cloudy.container.tar.gz - Container template.
* cloudy.iso - ISO image

==== Burn the ISO image (Linux) ====

The ISO file is a live install CD image, it means that it has installation system which is executed from a removable device (CD/DVD/USB) at boot.

You can burn it in:

* A CD or DVD:

$ apt-get install xorriso
$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed cloudy.iso

* A USB memory:

$ dd if=cloudy.iso of=${USBSTICK}

=== Compiling ===

In order to build or compile Cloudy some programs are needed in your machine to download the sources, generate the binaries, manipulate the ISO images, etc.

1. Download the needed packages (example with the ''apt'' tool in the Debian based systems):
sudo apt-get install build-essential live-build imagemagick curl debootstrap git unzip

2. Download the "builder" ''LBmake'' (Live-Build Make) to create the image:
git clone https://github.com/Clommunity/lbmake

3. Compile and generate the ISO image (and the Linux container):

* Go to the directory where you have downloaded the source of ''LBmake'' and compile it using the ''make'' tool:
cd lbmake
sudo make

4. Once the image is generated you can test it virtualizing the system with QEMU.<ref>QEMU processor emulator: http://wiki.qemu.org/Main_Page</ref>

* Generate a disk image and use the ISO image as a live CD for the installation:
qemu-img create -f qcow2 disk.qcow2 4G
qemu-system-i386 -enable-kvm -cdrom devel/binary.hybrid.iso -hda disk.qcow2

''NOTE: if you have a relatively recent machine, adding the option '-enable-kvm' you will take profit from the hardware virtualization, it will increase the speed and performance.''

==== Linux container ====

Optionally, from the ISO image you can create a Linux container with the following command:
sudo make container

''NOTE: before generating the container you have to create the ISO image first. If not, the previous command will generate firstly the ISO and after the container.''

== Installation ==

As it is explained in the introduction, the Cloudy distribution is based in Debian GNU/Linux and made in a live ISO image.

You can boot the system from the external device (CD/DVD/USB), or start the installation process by selecting the corresponding option from the menu.

[[File:cloudy-boot-install.png|center]]

The installation is the same as a standard Debian<ref>Debian installation procedure: http://www.debian.org/releases/stable/i386/</ref>, and the steps can be sumarize in:

=== Services ===

Below you can see what processes are currently available in Cloudy to be configured easily through the web interface.

''"NOTE: each service is explained in the Cloudy website<ref>Cloudy contents: http://cloudy.community/features/</ref>"''

==== Clommunity ====
* Getinconf (TincVPN client management)
* OpenVZ Web Panel (virtual machines management)
* Peer Streamer (distributed streaming)
* Syncthing (network file synchronization)
* Tahofe-LAFS (distributed file system)
* Webdav server

==== Guifi ====
* Proxy3 (web proxy)
[[File:cloudy-guifi-proxy.png|center]]

* SNPServices (monitoring/graphs)
[[File:cloudy-guifi-snpservices.png|center]]

* DNSServices (DNS)
[[File:cloudy-guifi-dnsservices.png|center]]

== References ==

<references/>

== External links ==

* http://cloudy.community
* http://wiki.clommunity-project.eu/soft:cloudservices
* http://clommunity-project.eu
* http://guifi.net

[[Category:Cloudy]]

Cloudy web UI

2015-05-12T19:12:08Z

Conxuro: Created page with " == Introduction == The Cloudy web User Interface (UI) uses an application called cDistro <ref name="cdistro">cDistro git repository: http://dev.cloudy.community/Guifi.net/we..."

== Introduction ==

The Cloudy web User Interface (UI) uses an application called cDistro <ref name="cdistro">cDistro git repository: http://dev.cloudy.community/Guifi.net/web-interface</ref>.

''(Add what it is)''

== Configuration ==

The cDistro configuration is placed in /etc/cdistro.conf

By default it has the following format:

#cdistro config
SERVER="/usr/bin/php"
OPTS=""
BINDIP="0.0.0.0"
PORT="7000"
DOCROOT="/var/local/cDistro"
# SSHAUTH=1 <- check user with ssh2 connection http://www.php.net/manual/en/function.ssh2-auth-password.php (Require: libssh2-php)
SSHAUTH=1
# LOGIN="root"
## PASSWORD = md5(md5('secret')) => php -r 'echo md5(md5("secret"))."\n";'
#PASSWORD="7022cd14c42ff272619d6beacdc9ffde"
PORT_SSL=7443

=== SERVER ===

The path of the PHP executable.

'''Example:'''

* "/usr/bin/php" - in the case of Cloudy (Debian).

=== OPTS ===

PHP options.

''(Add references or more info and an example)''

=== BINDIP ===

The IP address where the service will be listening.

'''Example:'''

* "127.0.0.1" - will accept only petitions from localhost.
* "0.0.0.0" - will accept petitions from any address.

=== PORT ===

The port opened by the service to listen to requests.

'''Example:'''

* "7000" - opens the port 7000.

=== DOCROOT ===

The path of the cDistro application.

'''Example:'''

* "/var/local/cDistro" - in the case of Cloudy.

=== SSLAUTH ===

Parameter that allows authentication via SSH2 in the application, i.e., to use the credentials that the SSH server of the system allows.

Can be 0 or 1.

'''Example:'''

* "1" - actives this option.
* "0" - disables this option (will require to define user and password).

=== LOGIN ===

The username to authenticate against the application.

Should be a string without spaces.

'''Example:'''

* "cloudy" - this user can log-in with the password of PASSWORD.

=== PASSWORD ===

The password of the user defined in LOGIN.

Should be a hash over a hash MD5 (hexadecimal), i.e., a hash of the password hash: md5(md5("PASSWORD")).

'''Example:'''

* "46d934e0f59ff1e2272f9f5f7950e5d9" - the hash of the string "PASSWORD".

'''Examples of how to generate that hash in a terminal:'''

$ php -r 'echo md5(md5("PASSWORD"))."\n";'
46d934e0f59ff1e2272f9f5f7950e5d9
$ printf "PASSWORD" | md5sum | awk '{printf $1}' | md5sum | awk '{print $1}'
46d934e0f59ff1e2272f9f5f7950e5d9

=== PORT_SSL ===

Port that Cloudy will use in the web interface with HTTPS (if SSL is enabled).

'''Example:'''

* "7443" - access to the web interface in https://IP_SERVIDOR:7443.

== References ==

<references/>

[[Category:Cloudy]]

Cloudy

2015-05-12T18:23:09Z

Conxuro: Redirected page to Category:Cloudy

#REDIRECT [[Category:Cloudy]]

Cloudy plug-ins

2015-05-12T18:22:53Z

Conxuro:

== 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 "the controller". 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><?PHP
//peerstreamer.menu.PHP
addMenu('Pastecat','pastecat','Clommunity');</pre>
By now, we'll use a very simple PHP script in the controller:

<pre><?PHP
//pastecat
$title="Pastecat";

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

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

return(array('type' => 'render','page' => $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="/opt/pastecat/"

doInstall() {
if isInstall
then
echo "Pastecat is already installed."
return
fi

# Creating directory and switching
mkdir -p $pcpath && 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 ] && return 0
return 1
}

case $1 in
"install")
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'=>t('Create a Pastecat server'),'href'=>$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("Write the port to publish your Pastecat service"));
$page .= createForm(array('class'=>'form-horizontal'));
$page .= addInput('description',t('Describe this server'));
$page .= addSubmit(array('label'=>t('Publish'),'class'=>'btn btn-primary'));
$page .= addButton(array('label'=>t('Cancel'),'href'=>$staticFile.'/peerstreamer'));

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

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

$page = "<pre>";
$page .= _pcsource($description);
$page .= "</pre>";

return(array('type' => 'render','page' => $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 = "";
$device = getCommunityDev()['output'][0];
$ipserver = getCommunityIP()['output'][0];

if ($description == "") $description = $type;

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

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

$page .= addButton(array('label'=>t('Back'),'href'=>$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
"install")
shift
doInstall $@
;;
"publish")
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:-""}
local description=${2:-""}
local ip=${3:-"0.0.0.0"}

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

# Running pastecat
cmd='su '$PCUSER' -c "{ '$PCPATH$PCPROG' -l :'$port' > '$LOGFILE' 2>&1 & }; echo \$!"'
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 "false connections"

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="/opt/pastecat/"
PCPROG="pastecat"
LOGFILE="/dev/null"
PCUSER="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="$pidpc http://$ip:$port" # Separator is space character
echo $info > $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 "stop" 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 .= "<div class='alert alert-success text-center'>".t("Pastecat is installed")."</div>\n";
if ( isRunning() ) {
$page .= "<div class='alert alert-success text-center'>".t("Pastecat is running")."</div>\n";
$page .= addButton(array('label'=>t('Go to server'),'href'=>'http://'. getCommunityIP()['output'][0] .':'. $port));
$page .= addButton(array('label'=>t('Stop server'),'href'=>$staticFile.'/pastecat/stop'));
} else {
$page .= "<div class='alert alert-error text-center'>".t("Pastecat is not running")."</div>\n";
}
$page .= addButton(array('label'=>t('Create a Pastecat server'),'href'=>$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 = "";
$cmd = $pcutils." stop ";
execute_program_detached($cmd);

return(array('type'=>'redirect','url'=>$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>"stop")
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, "");
$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 = "";
$device = getCommunityDev()['output'][0];
$ipserver = getCommunityIP()['output'][0];

if ($description == "") $description = $type;

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

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

$page .= addButton(array('label'=>t('Back'),'href'=>$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><?PHP
// plug/avahi/pastecat.avahi.PHP

addAvahi('pastecat','fpcserver');

function fpcserver($dates){
global $staticFile;

return ("<a class='btn' href='http://" .$dates['ip'] .":". $dates['port']."'>Go to server</a> ");
}</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]]

Category:Cloudy

2015-05-12T18:22:17Z

Conxuro: Created page with "More information: * http://cloudy.community * http://wiki.clommunity-project.eu/soft:cloudservices"

More information:
* http://cloudy.community
* http://wiki.clommunity-project.eu/soft:cloudservices

Cloudy plug-ins

2015-04-22T15:47:46Z

Conxuro:

== 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 "the controller". 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><?PHP
//peerstreamer.menu.PHP
addMenu('Pastecat','pastecat','Clommunity');</pre>
By now, we'll use a very simple PHP script in the controller:

<pre><?PHP
//pastecat
$title="Pastecat";

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

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

return(array('type' => 'render','page' => $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="/opt/pastecat/"

doInstall() {
if isInstall
then
echo "Pastecat is already installed."
return
fi

# Creating directory and switching
mkdir -p $pcpath && 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 ] && return 0
return 1
}

case $1 in
"install")
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'=>t('Create a Pastecat server'),'href'=>$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("Write the port to publish your Pastecat service"));
$page .= createForm(array('class'=>'form-horizontal'));
$page .= addInput('description',t('Describe this server'));
$page .= addSubmit(array('label'=>t('Publish'),'class'=>'btn btn-primary'));
$page .= addButton(array('label'=>t('Cancel'),'href'=>$staticFile.'/peerstreamer'));

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

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

$page = "<pre>";
$page .= _pcsource($description);
$page .= "</pre>";

return(array('type' => 'render','page' => $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 = "";
$device = getCommunityDev()['output'][0];
$ipserver = getCommunityIP()['output'][0];

if ($description == "") $description = $type;

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

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

$page .= addButton(array('label'=>t('Back'),'href'=>$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
"install")
shift
doInstall $@
;;
"publish")
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:-""}
local description=${2:-""}
local ip=${3:-"0.0.0.0"}

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

# Running pastecat
cmd='su '$PCUSER' -c "{ '$PCPATH$PCPROG' -l :'$port' > '$LOGFILE' 2>&1 & }; echo \$!"'
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 "false connections"

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="/opt/pastecat/"
PCPROG="pastecat"
LOGFILE="/dev/null"
PCUSER="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="$pidpc http://$ip:$port" # Separator is space character
echo $info > $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 "stop" 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 .= "<div class='alert alert-success text-center'>".t("Pastecat is installed")."</div>\n";
if ( isRunning() ) {
$page .= "<div class='alert alert-success text-center'>".t("Pastecat is running")."</div>\n";
$page .= addButton(array('label'=>t('Go to server'),'href'=>'http://'. getCommunityIP()['output'][0] .':'. $port));
$page .= addButton(array('label'=>t('Stop server'),'href'=>$staticFile.'/pastecat/stop'));
} else {
$page .= "<div class='alert alert-error text-center'>".t("Pastecat is not running")."</div>\n";
}
$page .= addButton(array('label'=>t('Create a Pastecat server'),'href'=>$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 = "";
$cmd = $pcutils." stop ";
execute_program_detached($cmd);

return(array('type'=>'redirect','url'=>$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>"stop")
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, "");
$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 = "";
$device = getCommunityDev()['output'][0];
$ipserver = getCommunityIP()['output'][0];

if ($description == "") $description = $type;

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

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

$page .= addButton(array('label'=>t('Back'),'href'=>$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><?PHP
// plug/avahi/pastecat.avahi.PHP

addAvahi('pastecat','fpcserver');

function fpcserver($dates){
global $staticFile;

return ("<a class='btn' href='http://" .$dates['ip'] .":". $dates['port']."'>Go to server</a> ");
}</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

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