Afficher/cacher Sommaire
Commandes pratiques en Shell
À partir de YunoHost 2.4, de nouvelles commandes pratiques (helpers) en shell sont disponible pour faciliter le packaging, particulièrement pour des tâches répétitives comme la génération de mot de passe, la création de base de données MySQL…
Des exemples sont disponibles dans l’application d’exemple. Il est conseillé d’utiliser les commandes pratiques.
Vous pourrez les retrouver dans ce dépôt.
Pour pouvoir utiliser les helpers, il faudra ajouter les lignes suivantes au début des scripts shell :
# Source app helpers
source /usr/share/yunohost/helpers
Le script helpers va exécuter tout les scripts présent dans helpers.d et donc charger les fonctions des helpers. Afin qu’elles puissent être appelées simplement.
Liste non exhaustive des helpers disponibles
Base de données
ynh_mysql_execute_as_root SQL DB
Exécute la commande SQL
SQL
en tant que l’utilisateur root sur la base de donnéesDB
(ce dernier argument est optionnel).
ynh_mysql_execute_file_as_root FILE DB
Exécute les commandes SQL contenues dans le fichier
FILE
en tant que l’utilisateur root sur la base de donnéesDB
(ce dernier argument est optionnel).
ynh_mysql_create_db DB USER PWD
Crée la base de données
DB
et donne tous les droits sur celle-ci à l’utilisateurUSER
(automatiquement créé) identifié par le mot de passePWD
.
ynh_mysql_drop_db DB
Supprime la base de données
DB
.
ynh_mysql_drop_user USERNAME
Supprime l’utilisateur MySQL
USERNAME
MySQL.
ynh_mysql_dump_db DB > ./FILE
Exporte la base de données
DB
dans le fichierFILE
.
Gestion des paquets Debian
ynh_package_is_installed PACKAGE
Détermine si le paquet
PACKAGE
est installé sur le système.
La sortie de la commande doit être testée pour en connaître le résultat. Par exemple :if ! ynh_package_is_installed "yunohost" ; then echo "Oups, le paquet n'est pas installé." else echo "Le paquet est installé !" fi
ynh_package_version PACKAGE
Retourne la version du paquet
PACKAGE
installé sur le système.
ynh_package_update
Met à jour la liste des paquets disponibles de manière silencieuse et non interactive.
C’est unapt-get update
avec les options -y -qq et noninteractive.
Attention, les commandes suivantes sont à éviter autant que possible. Il n’est pas sain d’installer et encore moins de supprimer un paquet sans en gérer les conflits et dépendances. Ceci sera bientôt facilité dans les prochaines versions de YunoHost…
ynh_package_install PACKAGE1 PACKAGE2
Installe les paquets
PACKAGE1
,PACKAGE2
, etc de manière non interactive et silencieuse.
C’est unapt-get install
avec les options -y -qq et noninteractive.
ynh_package_remove PACKAGE1 PACKAGE2
Supprime les paquets
PACKAGE1
,PACKAGE2
, etc de manière non interactive et silencieuse.
C’est unapt-get remove
avec les options -y -qq et noninteractive.
ynh_package_autoremove PACKAGE1 PACKAGE2
Supprime les paquets
PACKAGE1
,PACKAGE2
, etc ainsi que tous les paquets qui ne semblent plus utilisé, de manière non interactive et silencieuse.
C’est unapt-get autoremove
avec les options -y -qq et noninteractive.
Configuration des applications
ynh_app_setting_set APP KEY VALUE
Stocke le réglage nommé
KEY
dont la valeur estVALUE
pour l’applicationAPP
, afin de le réutiliser plus tard (typiquement dans le scriptupgrade
) ou pour que YunoHost puisse se configurer automatiquement (par exemple pour le SSO).
Les réglages sont stockés dans le fichier /etc/yunohost/apps/${APP}/settings.yml.
Par exemple, pour stocker le paramètre de visibilité, privé ou public, d’une application, on notera ainsi :ynh_app_setting_set nom_app is_public "yes"
Le SSO fait appel aux réglages stockés pour l’application afin de déterminer si cette dernière peux être accessible publiquement ou non.
Pour cela, 6 clés différentes sont disponible :
Tout d’abord skipped_uris
, unprotected_uris
et protected_uris
. Ces 3 clés sont relatives au chemin (ou path) de l’application.
Par exemple :
ynh_app_setting_set nom_app skipped_uris "/"
concernera la racine de l’application, soit https://domain.tld/path_app/ ainsi que tout ce qui suivra. Alors que :
ynh_app_setting_set nom_app skipped_uris "/blog"
concernera le path /blog de l’application, soit https://domain.tld/path_app/blog et ce qui suivra, mais pas https://domain.tld/path_app/.
skipped_uris
Une url ajoutée avec la clé skipped_uris sera totalement ignorée par le SSO, donc l’accès sera public et ne prendra pas en compte un utilisateur déjà connecté.
unprotected_uris
Une url ajoutée avec la clé unprotected_uris sera accessible publiquement, mais un utilisateur connecté au SSO pourra se connecter en utilisant le header HTTP.
protected_uris
Une url ajoutée avec la clé protected_uris sera bloquée par le SSO et accessible uniquement aux utilisateurs authentifiés.
Les clés skipped_regex
, unprotected_regex
et protected_regex
sont les équivalents en “expressions régulières” des 3 clés précédentes.
Il est important de noter que ce ne sont pas véritablement des expressions régulières qui seront interprétés, mais des patterns lua, dont la syntaxe différe légèrement.
Plus d’infos sur la syntaxe des patterns lua. Ainsi que quelques exemples.
Les patterns utilisant des regex, contrairement aux précédents, sont recherchés sur la totalité de l’URL, et non uniquement sur la partie spécifique à l’application. Il convient donc d’écrire des patterns qui englobent l’URL entière (incluant domaine et chemin). Par exemple, si on souhaite placer skipped_regex sur /blog en considérant une suite de chiffres indéfinie en argument. On indiquera ceci :ynh_app_setting_set nom_app skipped_regex "$domain$path/blog%?%d+$"
Cela pose toutefois un éventuel problème, si les variables $domain ou $path contiennent un tiret (-), celui-ci sera interprété comme étant un caractère magique du pattern. Il faut donc échapper les éventuels tirets avec un %.
domainregex=$(echo "$domain" | sed 's/-/\%&/g') pathregex=$(echo "$path" | sed 's/-/\%&/g') ynh_app_setting_set nom_app skipped_regex "$domainregex$pathregex/blog%?%d+$"
ynh_app_setting_get APP KEY
Récupère le paramètre
KEY
stocké précémment pour l’applicationAPP
.
Par exemple :is_public=$(ynh_app_setting_get nom_app is_public)
ynh_app_setting_delete APP KEY
Supprime le paramètre
KEY
enregistré pour l’applicationAPP
.
Gestion des utilisateurs
ynh_user_exists USERNAME
Vérifie l’existence de l’utilisateur
USERNAME
dans Yunohost.
La sortie de la commande doit être testée pour en connaître le résultat. Par exemple :if ynh_user_exists "johndoe" ; then echo "L'utilisateur existe !" fi
ynh_user_get_info USERNAME KEY
Récupère l’information
KEY
sur l’utilisateurUSERNAME
.
Les valeurs possibles deKEY
sont :
- firstname
- fullname
- lastname
- mail-aliases
- mailbox-quota
Par exemple :mailadmin=$(ynh_user_get_info $admin mail)
ynh_system_user_exists USERNAME
Détermine si l’utilisateur
USERNAME
existe sur le système.
La sortie de la commande doit être testée pour en connaître le résultat. Par exemple :if ynh_system_user_exists "www-data" ; then echo "L'utilisateur existe sur le système !" fi
ynh_system_user_create USER_NAME [HOME_DIR]
Créer l’utilisateur système
USER_NAME
, si il n’existe pas déjà.
Si aucun dossier home n’est mentionné, l’utilisateur sera créé sans home.
Nécessite YunoHost version 2.6
ynh_system_user_delete USER_NAME
Supprime l’utilisateur système
USER_NAME
.
Nécessite YunoHost version 2.6
Gestion des ports
ynh_find_port BEGIN_PORT
Cherche un port libre en commençant par
BEGIN_PORT
Le numéro de port trouvé est renvoyé en fin de commande.port=$(ynh_find_port 8080)
Nécessite YunoHost version 2.6
Autres commandes
ynh_string_random LENGTH
Génère une chaine de caractères aléatoires de longueur
LENGTH
(par défaut 24).
ynh_die MSG RETCODE
Affiche le message
MSG
(sur stderr) et termine le script avec le codeRETCODE
(par défaut 1).
Les commandes suivantes sont amenées à être remplacées (voir supprimées) dans les prochaines versions de YunoHost.
sudo yunohost firewall allow [--no-upnp] {TCP,UDP,Both} PORT
Ouvre le port
PORT
sur le parefeu en TCP, UDP ou les deux. L’ouverture automatique des ports via upnp peux être désactivé sur ce port en spécifiant l’option--no-upnp
.
sudo yunohost firewall disallow {TCP,UDP,Both} PORT
Ferme le port
PORT
sur le parefeu en TCP, UDP ou les deux.
sudo yunohost app checkurl DOMAINPATH -a APP
Vérifie la disponibilité du chemin DOMAIN/PATH. Il est utile pour les applications web et vous permet d’être sûr que le chemin n’est pas utilisé par une autre application. Si le chemin est inutilisé, elle le « réserve » pour l’application APP.
Remarque : ne pas préfixer parhttp://
ou parhttps://
dans leDOMAINPATH
.
sudo yunohost app addaccess [--users=USER] APP
Autorise l’utilisateur
USER
à accéder à l’applicationAPP
. Si l’option--users
n’est pas spécifiée, l’accès à l’applicationAPP
est accordé à tout les utilisateurs.
sudo yunohost app removeaccess --users=USER APP
Retire l’autorisation d’accès de l’utilisateur
USER
à l’applicationAPP
.
sudo yunohost service add NAME [-l LOG]
Ajoute le service
NAME
dans l’interface de gestion admin de YunoHost. Le fichier de log du service peux être ajouté avec l’option-l
en indiquant son chemin absolu.
sudo yunohost service remove NAME
Retire le service
NAME
dans l’interface de gestion admin de YunoHost.
sudo yunohost app ssowatconf
Cette commande régénère la configuration du SSO. Elle est appelée automatiquement à la fin du script.
Mais peux être appelée avant si nécessaire.
Exemple
Private
root@xeuyakzas:/home/yak# source /usr/share/yunohost/helpers
root@xeuyakzas:/home/yak# ynh_app_setting_set dokuwiki is_public "no"
root@xeuyakzas:/home/yak# ynh_app_setting_set dokuwiki protected_uris "/"
root@xeuyakzas:/home/yak# yunohost app ssowatconf