Cloudy plug-ins

De Guifi.net - Wiki Català

Què és un plug-in?

Cloudy és una distribució de Linux basada en Debian que dona als usuaris una interfície simple i còmode per gestionar diferents serveis que poden ser fets servir a través d'una xarxa comunitària; en el nostre cas, Guifi.

Al mateix temps, Cloudy ofereix una sèrie d'eines que permeten a un usuari afegir un servei del seu gust sense haver de tenir coneixements molt complexos sobre xarxes i informàtica en general. De manera automàtica, aquests serveis es publiquen mitjançant Avahi, i tothom que tingui Cloudy pot fer ús d'aquest servei.

Una altra manera d'anomenar aquests serveis que es poden posar i treure de forma senzilla és plug-in. Així doncs, entenem per plug-in un programa o software que un usuari vol afegir a la distribució i que pot ser gestionat de forma senzilla des de l'interfície web.

Afegir serveis a Cloudy

Una petita introducció

Aquesta guia t'ensenyarà el procés per afegir un nou servie a la distribució Cloudy.

Per tal de ser clar i donar alguns exemples al mateix temps, integrarem un servei bastant simple mostrant alguns troços de codi pel camí.

Per simplicitat farem servir Pastecat[1]. És un bon candidat ja que:

  • És independent i no es federa ni es comunica amb altres nodes
  • Està fet en Go, és fàcil de distribuïr i instal·lar
  • No necessita fitxers de configuració
  • No necessita gaires recursos

1. Obtenint el binari

El primer que hem d'investigar és com descarregar i instal·lar el binari a Cloudy. La majoria del software que podem trobat està per defecte en els paquets de Debian, però el Pastecat no hi és. Si es donés el cas que hi fós, tan sols hauriem d'executar la comanda apt-get install pastecat des de PHP.

Però com que aquest no és el cas, haurem de treure el binari d'algun altre lloc. Una opció és agafar el codi font i compilarl-lo nosaltres mateixos, però el problema d'això és que Cloudy necessitaría incloure moltes eines i llibreries per compil·lar, i aquest no és l'objectiu.

La millor opció si un paquet de Debian no està disponible en els repositoris, és descarregar els binaris des d'algun lloc segur. Podem fer servir el servei de "releases" de Github per això. Les dues opcions ens deixen amb un fitxer executable que hauriem de ser capaços de córrer directe sobre Cloudy.

En aquest cas en particular descarregarem els binaris des del repositori git amb la següent línia de comandes:

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

Noteu que en aquest cas en concret estem descarregant una versió específica per un Linux amb arquitectura i386.

Fixeu-vos però, que tenir el servei en els paquets de Debian té moltes avantatges:

  • Les actualitzacions són simples i no necessiten feina extra des de Cloudy
  • El paquet està compilat per Debian d'una manera segura
  • Els fitxer de l'init.d ja venen per defecte
  • Els paquets de Debian solen contenir correccions

2. Provant-lo

Abans d'afegir un servei hauriem de configurar-lo i provar-lo directament nosaltres mateixos per veure com funciona i que realment funciona. També hem entendre quines opcions de configuració o línies de comandes necessitarem per fer ús d'aquest servei en particular i com el gestionarem un cop estigui funcionant.

3. Afegint el controlador

En web/plug/controllers tenim un fitxer PHP per cada servei anomenat controlador (o 'controller' en anglès). Aquest fitxer conté el codi que s'executarà quan es visiti la pàgina del nostre servei des de la interfície web de Cloudy.

3.1. Afegint la funció índex

El que volem fer és que el nostre servei estigui integrat en l'estructura web de Cloudy. Per fer això, necessitem crear uns quants 'scripts' en PHP i afegir-los al nostre dispositiu. De moment necessitarem crear dos scripts: pastecat.php i pastecat.menu.php. El primer fitxer és el controlador, és a dir, l'script que renderitza la pàgina i té tota la informació tal com botons o redireccionaments. L'altre és el que permet que el nostre servei es mostri en els menus superiors desplegables de Cloudy.

El codi del menú serà quelcom semblant a això:

   <?php
   //peerstreamer.menu.php
   addMenu('Pastecat','pastecat','Clommunity');

Per ara, farem servir un script molt simple en PHP com a controlador:

   <?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));
   }

En el nostre sistema Cloudy, aquests fitxers han de posar-se als directoris dins de /var/local/cDistro/plug/. El primer de tot ha d'anar dins de menus i el segon al directori controllers. Un cop haguem fet això, podem anar al web del nostre dispositiu amb Cloudy i accedir al nou menú Pastecat.

3.2. Fent que el controlador instal·li el nostre servei

Com s'ha mencionat anteriorment, aquest pas és molt més senzill de realitzar si el servei està en els paquets de Debian. Com que no és el cas del pastecat, ho haurem de fer manualment. Normalment, fer aquest procés manualment inclou una combinació de les comandes wget, mv i chmod. En general, és bona idea mantenir els fitxers d'aquest tipus de serveis a /opt/SERVICENAME.

En el nostre cas en particular, la primera cosa que necessitem fer és descarregar el binari de la 'release' de Github. per tal de fer això farem ús de la comanda mencionada abans: wget. Donada una URL a un fitxer, aquesta comanda en permet descarregar aquest fitxer al nostre sistema, i això és el que farem tot seguit amb:

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

Una cop tinguem el binari en la nostre màquina el mourem al directori /opt/pastecat/. per tal de moure els fitxers pel nostre sistema farem servir la comanda mv. Tot i així, primer haurem de crear el directori on posarem el fitxer. Per fer això, utilitzarem mkdir de la següent manera:

  mkdir -p /opt/pastecat/

Una vegada haguem creat el directori, és hora de moure-hi el binari:

   mv current_directory/pastecat_linux_386 /opt/pastecat/

On 'current_directory és el directori on prèviament hem descarregat el binari. Com que el nom del binari depèn de l'arquitectura, per tal de simplificar el codi del controlado, canviarem el nom del fitxer executable a quelcom més genèric i simple:

   mv /opt/pastecat/pastecat_linux_386 /opt/pastecat/pastecat

Ara el nostre binari es diu pastecat en comptes de pastecat_linux_386

Aquests passos són els mínim requerits per instal·lar un servei que no s'ofereix directament en els repositoris oficials de Debian. Nogensmenys, de cara a un usuari final, seria un malson haver de fet totes aquestes comandes en una consola connectat a través de ssh al seu dispositiu, així que el que farem tot seguit és crear un script en bash que serà cridat més endavant a través de la interfície web clicant un botó.

Aquest script és la primera versió del controlador del pastecat. Per ara només inclourem una funció per instal·lar el pastecat en el nostre dispositiu. Més endavant onclourem algunes altres funcions per proveïr al nostre script amb més serveis:

   #!/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

Podem veure com els últims passos s'han concentrat dins d'una mateixa funció, permetent-nos instal·lar el software en el dispositiu d'una forma més senzilla.

3.3 Fent que el controlador utilitzi pastecat

3.3.1 Executar el servei

El següent que volem fer és que el nostre software es pugui fer servir des de la interfície web. És per això que inclourem una nova opció a la nostra pàgina principal de pastecat i inclourem una nova funció en el nostre controlador per gestionar el binari. Afegirem un botó en el PHP de la següent manera:

   $page .= addButton(array('label'=>t('Create a Pastecat server'),'href'=>$staticFile.'/pastecat/publish'));

just després del missatge Pastecat is installed. El proper que cal fer és implementar la funció publish en el mateix PHP. Aquesta funció és la responsable de cridar la funció corresponent en el controlador i anunciar el nostre servei fent servir Avahi. La diferència amb aquesta funció és que requereix un formulari per introduïr-hi dades, així que al final acabarem tenint dues funcions: una get i una post:

   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 = "
";
        $page .= _pcsource($description);
        $page .= "
";
       return(array('type' => 'render','page' => $page));
   }

Com podem veure en la funció post estem invocant una altra funció. La raó de fer això és escriure un codi més simple i modular. En aquesta última funció per fi cridem a l'script:

   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)
   }

El proper que hem de fer és crear una funció publish en el controlador, així que afegirem una nova funció al controlador bàsic que teniem a la secció 3.2. Primer afegirem un nou paràmetre anomenat "publish", així que la primera part a exeutar-se de l'script serà:

   if [ $# -lt 1 ]
   then
       doHelp
   fi
   
   case $1 in
       "install")
           shift
           doInstall $@
           ;;
       "publish")
           shift
           doServer $@
           ;;
   esac

Com podem veure, quan el primer argument de l'script és publish, "shiftem" la resta d'arguments i cridem a la funció doServer. En aquesta funció hem de posar en marxa el servei amb els arguments corresponents, així que el primer que farem serà posar aquests paràmetres en variables locals. Una vegada haguem fet això, el més lògic sería llençar l'aplicació directament, però com que l'script es crida amb permisos de "root" (i això és dolent) hem de llençar Pastecat com a usuari nobody. El problema és que l'usuari nobody no té quasi permisos... i el Pastecat necessita alguns permisos per crear directoris i fitxers de text. Per permetre que nobody pugui fer aquestes coses, primer crearem un directori garantint permisos a casibé tothom. Per aconseguir això, farem servir la comanda chmod altre vegada. Ara, l'usuari pot crear fitxers i directoris dins d'aquest mateix directori, i en conseqüència, podem córrer Pastecat. Finalment, mantindre el PID en una variable en cas que el necessitem més endavant (que ja us dic que sí que el necessitarem):

   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
   }

Fixeu-vos que ara estem fent servir algunes variables globals que no estaven definides abans, com ara PCUSER i LOGFILE. Aquestes variables tenen els següents valors:

   PCPATH="/opt/pastecat/"
   PCPROG="pastecat"
   LOGFILE="/dev/null"
   PCUSER="nobody

Més informació

Més info si cal


Referències

  1. (https://github.com/mvdan/pastecat)


Enllaços externs

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

Eines de l'usuari