.default}){kind=icon}
YunoHost is an **operating system** aiming to **simplify server administration** and therefore democratize [self-hosting](/admin/about_self_hosting) while making sure it stays reliable, secure, ethical and lightweight. It is a copylefted libre software project maintained by volunteers. Technically, it can be seen as a server distribution based on [Debian GNU/Linux](https://debian.org).
YunoHost can be installed on [many kinds of hardware](/admin/get_started/install_on), either at home or on a remote server (VPS).
## Features
- 
================================================
FILE: docs/admin/05.get_started/02.why_should_you_not_host_yourself.mdx
================================================
---
title: Why should you (not?) host yourself?
hide_table_of_contents: true
description: " "
hide_title: true
---
## Why should you host yourself?
- **You believe in a free, open and decentralized internet.** In a centralized internet, private companies and government can spy, analyze and influence people by dictating how they connect with each other, and by filtering content. YunoHost is developed by a community who believe in an open and decentralized internet, and we hope that you do, too!
- **You want to have control of your data and services.** Your pictures, chat messages, browsing history, and that text you are writing for school, have nothing to do on somebody else's server (a.k.a. The Cloud). They are part of your private life, but also part of your family's life, your friend's life, and so on. These data should be managed by *you*, not a random company in the US who wants your data to analyze them and sell the results.
- **You want to learn about how computers and the Internet work.** Operating your own server is a pretty good context to understand the basic mechanisms at the heart of operating systems and the Internet. You might have to deal with command line interface, network architecture, DNS configuration, SSH, and so on.
- **You want to explore new possibilities and customize things.** Ever dreamed of running a Minecraft server for you friends, or a persistent IRC or XMPP client? With your very own server, you can manually install and run virtually any program you want, and customize every bit.
## Why should you *not* host yourself?
- **Self-hosting requires some work and patience.** Hosting yourself is a bit like growing your own garden or vegetables: it requires work and patience. While YunoHost aims to do all the hard work for you, self-hosting still requires that you take time to learn and configure a few things to setup your server properly. You will also need to perform maintenance tasks (such as upgrades) from time to time, or to ask for support if some things break.
- **With great servers comes great responsibilities.** Operating a server means that you are responsible for the data you are hosting. Nobody will be able to recover them for you if they get lost. YunoHost provides backup features, which you should use regularly to backup the configurations and data you care about. You should also keep an eye on security news and recommendations so that your server or critical data don't get compromised.
- **Quality and performance probably won't be as good as premium services.** YunoHost (and most of the applications packaged for it) are free and open-source software, developed by communities of people in their free time and on the basis of best effort. There is no absolute guarantee that software will work in every possible circumstance. The performance of your self-hosted server is also related to its CPU and RAM, and to the available internet connectivity.
================================================
FILE: docs/admin/05.get_started/05.methods.mdx
================================================
---
title: Choose your self-hosting mode
hide_table_of_contents: true
---
You can host yourself at home (on a small computer), or on a remote server. Each solution has its pros and cons:
## At home, for instance on an ARM board or an old computer
You can host yourself at home with an ARM board or a re-purposed regular computer, connected to your home router/box.
- **Pros**: you will have physical control of the machine and only need to buy the hardware;
- **Cons**: you will have to [manually configure your internet box](/admin/get_started/post_install/port_forwarding) and [might be limited by your ISP](/admin/get_started/providers/isp/).
## At home, behind a VPN
A VPN is an encrypted tunnel between two machines. In practice, it makes it "as if" you were directly, locally, connected to your server machine, but actually from somewhere else on the Internet. This allows you to still host yourself at home, while bypassing possible limitations of your ISP. See also [the Internet Cube project](https://internetcu.be/) and [the FFDN](https://www.ffdn.org/).
- **Pros**: you will have physical control of the machine, and the VPN hides your traffic from your ISP and allows you to bypass its limitations;
- **Cons**: you will have to pay a monthly subscription for the VPN.
## On a remote server (VPS or dedicated server)
You can rent a virtual private server or a dedicated machine from [associative](https://db.ffdn.org/) or [commercial](/admin/get_started/providers/servers) "Cloud" providers.
- **Pros**: your server and its internet connectivity will be fast;
- **Cons**: you will have to pay a monthly subscription and won't have physical control of your server.
## Summary
export const styleNone = {
textAlign: 'center',
};
export const styleGood = {
textAlign: 'center',
backgroundColor: 'green',
color: 'white',
};
export const styleMeh = {
textAlign: 'center',
backgroundColor: 'darkgoldenrod',
color: 'white',
};
export const styleDanger = {
textAlign: 'center',
backgroundColor: 'brown',
color: 'white',
};
| At home (e.g. ARM board, old computer) |
At home behind a VPN |
On a remote server (VPS or dedicated) |
|
|---|---|---|---|
| Hardware cost | About 50€ (e.g. a Raspberry Pi) |
None | |
| Monthly cost | Negligible (electricity) |
Around 5€ (VPN) |
Starting at ~3€ (VPS) |
| Physical control of the machine | Yes | Yes | No |
| Manual port routing required | Yes | No | No |
| Possible ISP limitations | Yes (see here) |
Bypassed by VPN | Typically no |
| Internet connectivity | Depends on home connectivity | Typically pretty good | |
[See bug here](https://github.com/YunoHost/issues/issues/2419) | | [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) | | [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) | ================================================ FILE: docs/admin/05.get_started/10.providers/05.registrar/namecheap.mdx ================================================ --- sidebar_label: Namecheap title: Obtaining an API key from Namecheap --- See the [API Documentation](https://www.namecheap.com/support/api/intro/) for reference. 1. Login to your Namecheap account. 2. Go to the Profile > Tools menu. 3. Scroll down to the Business & Dev Tools section. Click on MANAGE next to Namecheap API Access. 4. Toggle ON/OFF, read our Terms of Service, enter your account password. 5. After enabling API access, you will be allotted an APIKey. Your Namecheap account username will act as API username. Your access to the API is authenticated using these elements. ================================================ FILE: docs/admin/05.get_started/10.providers/05.registrar/ovh/_category_.yaml ================================================ label: "OVH" ================================================ FILE: docs/admin/05.get_started/10.providers/05.registrar/ovh/autodns.mdx ================================================ --- sidebar_label: OVH DNS config via API title: Obtaining an API key from OVH --- This page is meant to guide you in obtaining an API key from OVH in order to configure YunoHost's automatic DNS configuration mecanism :::caution **DO NOT share your API tokens with anybody!** A malicious attacker obtaining your tokens could take over your domain, and possibly your server! ::: 1. Go to [the OVH token request page](https://eu.api.ovh.com/createToken/) 2. Fill the form with the required information as shown below: - Account ID or email address: This is your usual OVH login - Password: This is your usual OVH password - Script Name: for example `YunoHost Auto DNS` - Script description: for example `YunoHost Auto DNS` - Validity: `Unlimited` - Rights: use the `+` button to add the following lines - `GET` : `/domain/zone/*` - `POST` : `/domain/zone/*` - `PUT` : `/domain/zone/*` - `DELETE` : `/domain/zone/*`  3. You will obtain three tokens (an application key, a secret application key, and a consumer key) which should be used in YunoHost's configuration ================================================ FILE: docs/admin/05.get_started/10.providers/05.registrar/ovh/manualdns.mdx ================================================ --- sidebar_label: OVH manual DNS config title: DNS Configuration with OVH --- Let's see how to properly set the DNS redirections with [OVH](http://www.ovh.com). Once you bought your domain name, got to the Web Control Panel, and click on you domain name on the left side:  Click on the **DNS Zone** tab, then on **Add an entry**:  Now you need to add the DNS redirections as specified by the [standard DNS zone configuration](/admin/get_started/post_install/dns_config) Click on "Change in text format", keep the first four lines: ```text $TTL 3600 @ IN SOA dns104.ovh.net. tech.ovh.net. (2020083101 86400 3600 3600000 60) IN NS dns104.ovh.net. IN NS ns104.ovh.net. ``` then erase everything below, and replace it with the configuration generated by YunoHost as explained in [this page](/admin/get_started/post_install/dns_config). ### Dynamic IP [General tutorial on dynamic IP](/admin/tutorials/domains/dns_dynamicip). You should follow this part if you have a dynamic IP. Find out if your ISP provides you with a dynamic IP address [here](/admin/get_started/providers/isp/). Let's create a DynHost id. Follow [this tutorial](http://blog.developpez.com/brutus/p6316/ubuntu/configurer_dynhost_ovh_avec_ddclient) to install ddclient. ddclient will take care of telling OVH that the IP has changed. Then OVH will update the IP. You need to add in the configuration file: - your login and password DynHost - your domain name You should also check out [OVH's guide on DynHost](https://www.ovh.co.uk/g2024.hosting_dynhost). ================================================ FILE: docs/admin/05.get_started/10.providers/10.isp.mdx ================================================ --- title: Internet service providers hide_table_of_contents: true description: " " --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
ou Box OVH | ✔ | ✔ | ✔ | ✔ | … | | Free | Freebox | ✔ | ✔ | ✔ (sauf IPv6, pas de support, et buggué sur certaines plages d'adresses ipv4) | ✔ | ✘ | | SFR | Neufbox | ✔ | ✔/✘ | … | ✔/✘ | … | | Orange | Livebox | ✘ | ✔ (depuis la Livebox 4) | ✘ (XXX.pro.dns-orange.fr disponible sur les abonnements orange pro) | ✘ (en option depuis la Livebox 3 et sur les abonnements orange pro) | … | | Bouygues
Télécom | Bbox | ✔ | ✔ | ✘ | … | … | | Darty | Dartybox | ✔ | ✔ | ✘ | … | … | Pour une liste plus complète et précise, référez-vous à la très bonne documentation de [wiki.auto-hebergement.fr](http://wiki.auto-hebergement.fr/fournisseurs/fai#d%C3%A9tail_des_fai). :::tip [FDN](http://www.fdn.fr) fournit des [VPN](http://www.fdn.fr/-VPN-.html) permettant de rapatrier une (ou plusieurs sur demande) IPv4 fixe et un /48 en IPv6 et ainsi « nettoyer » votre connexion si vous êtes chez l’un des FAI *limitants* du tableau ci-dessus. :::
Réservé aux nordistes(FR 59) |
Réservé aux suisses |
WSL specific configuration
You will have to choose a fake domain, since it will not be accessible from outside. For example, `ynh.wsl`. The tricky part is advertising this domain to your host. Alter your `C:\Windows\System32\drivers\etc\hosts` file. You should have a line starting by `::1`, update it or add it if needed to get: ```text ::1 ynh.wsl localhost ``` If you want to create subdomains, do not forget to add them in the `hosts` file too: ```text ::1 ynh.wsl subdomain.ynh.wsl localhost ```
- Enter your domain name in the "Server" field, fill the "Security" and "Port" fields as per the IMAP row in the table above, then enter your password in the "Password" field and click "Next"
- Again, your domain name in the "Server" field, but fill the "Security" and "Port" fields as per the SMTP row in the table above, then enter your password in the "Password" field and click "Next"
Certaines Freebox [sont munies d'un disque dur connecté au réseau (NAS)](https://www.actusfree.fr/nas-freebox/) qui peut être utilisé comme espace de stockage depuis votre serveur. ## Utiliser le NAS de la Freebox Il faut installer le paquet `cifs-utils` ```bash sudo apt install cifs-utils ``` Il faut créer un point de montage (ici `/mount/freebox`) ```bash mkdir -p /mount/freebox ``` On monte le répertoire NAS par défaut avec les droits de lecture / écriture pour tous ```bash sudo mount -t cifs //mafreebox.freebox.fr/Disque\ dur/ /mount/freebox -o guest,iocharset=utf8,file_mode=0777,dir_mode=0777 ``` ### Automatiser le montage Une ligne à ajouter à la fin du `/etc/fstab` : ```text //mafreebox.freebox.fr/Disque\040dur/ /mount/freebox cifs _netdev,guest,uid=monlogin,gid=users,iocharset=utf8 0 0 ``` Le `_netdev` signale que c'est un périphérique réseau, afin que le système ne le monte que s'il a accès au réseau. `guest` est le mode d'identification à la Freebox : pour une connexion authentifiée, placez vos identifiants dans un fichier sous la forme ```text username=your_user password=your_pass domain=FREEBOX ``` et remplacez `guest` par `credentials=/path/to/file` (c'est aussi possible de spécifier directement `username=xx,password=xx` dans le fstab, mais déconseillé pour des raisons de sécurité) `uid` et `gid` sont pour les id user et group auxquels appartiendra le répertoire une fois monté. Par défault (sur la Freebox V5 en tout cas), ils se retrouvent avec les uid/gid de 4242. Il est aussi possible de mettre des droits particuliers avec les paramètres `file_mode=0777,dir_mode=0777`. ================================================ FILE: docs/admin/45.tutorials/_category_.yaml ================================================ label: "📜 Tutorials" link: type: "generated-index" title: "📜 Tutorials" ================================================ FILE: docs/admin/50.troubleshooting/03.cleanup.mdx ================================================ --- title: Cleaning up space hide_table_of_contents: true --- If your system runs out of space, you may an emergency option to get back some bit of space, and investigate what's taking up space ## Execute the basic-space-cleanup tool One may use the following command, to perform basic space cleanup (apt, journalctl, logs, ...) : ```bash sudo yunohost tools basic-space-cleanup ``` Additionaly, you may want to cleanup YunoHost operation logs if they are taking too much space, cf [this issue](https://github.com/YunoHost/issues/issues/2329). ## Explore what's taking up space Install `ncdu`: ```bash sudo apt install ncdu ``` Then use it to scan the filesystem and have a dynamic, browsable report of what's using space: ```bash ncdu / ``` or `ncdu /var/`, for example to scan only `/var/` ================================================ FILE: docs/admin/50.troubleshooting/05.fail2ban.mdx ================================================ --- title: IP address unban hide_table_of_contents: true --- **Fail2Ban** is an intrusion prevention software that protects computer servers against brute-force attacks. It monitors certain logs and will ban IP addresses that show brute-force-like behavior. In particular, **Fail2Ban** monitors `SSH` connection attempts. After 5 failed SSH connection attempts, Fail2Ban will ban the IP address from connecting via SSH for 10 minutes. If this address fails several times, it might get banned for a week. ## Unban an IP address To unblock an IP address, you must first access your server by some means (for example from another IP address or from another internet connection than the banned one). Then, look at the **Fail2Ban’s log** to identify in which `jail` the IP address has been banned: ```bash sudo tail /var/log/fail2ban.log 2019-01-07 16:24:47 fail2ban.filter [1837]: INFO [sshd] Found 11.22.33.44 2019-01-07 16:24:49 fail2ban.filter [1837]: INFO [sshd] Found 11.22.33.44 2019-01-07 16:24:51 fail2ban.filter [1837]: INFO [sshd] Found 11.22.33.44 2019-01-07 16:24:54 fail2ban.filter [1837]: INFO [sshd] Found 11.22.33.44 2019-01-07 16:24:57 fail2ban.filter [1837]: INFO [sshd] Found 11.22.33.44 2019-01-07 16:24:57 fail2ban.actions [1837]: NOTICE [sshd] Ban 11.22.33.44 2019-01-07 16:24:57 fail2ban.filter [1837]: NOTICE [recidive] Ban 11.22.33.44 ``` Here, the `11.22.33.44` IP address has been banned in the `sshd` and `recidive` jails. Then deban the IP address with the following commands: ```bash sudo fail2ban-client set sshd unbanip 11.22.33.44 sudo fail2ban-client set recidive unbanip 11.22.33.44 ``` ## Whitelist an IP address If you don’t want a "legitimate" IP address to be blocked by **YunoHost** anymore, then you have to fill it in the whitelist of the `jail` configuration file. When updating the **Fail2Ban** software, the original `/etc/fail2ban/jail.conf` file is overwritten. So it is on a new dedicated file that we will store the changes. They will thus be preserved over time. 1. Start by creating the new jail configuration file which will be called `yunohost-whitelist.conf`: ```bash sudo touch /etc/fail2ban/jail.d/yunohost-whitelist.conf ``` 2. Edit this new file with your favorite editor: ```bash sudo nano /etc/fail2ban/jail.d/yunohost-whitelist.conf ``` 3. Paste the following content into the file and adapt the IP address `XXX.XXX.XXX.XXX`: ```bash [DEFAULT] ignoreip = 127.0.0.1/8 XXX.XXX.XXX.XXX #<= the IP address (you can put more than one, separated by a space) that you want to whitelist ``` 4. Save the file and reload the Fail2Ban configuration: ```bash sudo fail2ban-client reload ``` Congratulations, no more risks of banning yourself from your own YunoHost server! ================================================ FILE: docs/admin/50.troubleshooting/10.change_root_password.mdx ================================================ --- title: Changing root's password hide_table_of_contents: true --- In the past, YunoHost had a special "`admin`" user in addition to `root`. This is not the case anymore, and each user admin password can be changed via the regular process. `root`, a.k.a "god on the machine", still exists however, and being able to access the root account can sometimes be useful. For example, because LDAP (the user database powering YunoHost account) is broken. In this case, you may be able to connect to root via SSH *from the local network*, via a direct screen/keyboard access, or via a rescue console provided by your VPS provider - depending on the nature of your server. ## Using the web administration interface First, connect to your web administration. Then go to Tools > YunoHost settings > Security tab > Change root password ## Using the command line interface ```bash yunohost tools rootpw ``` ================================================ FILE: docs/admin/50.troubleshooting/15.noaccess.mdx ================================================ --- title: Get access back into YunoHost --- There are several reasons that could lead to one administrator's access being partially or completely blocked off their YunoHost server. In numerous cases, one of the access methods is blocked, but others are not. This page will help you diagnose the issue, get back access, and if needed repair your system. Most common causes are listed first, so follow the tutorial from top to bottom. ## You have access to the server with its local IP address, but not its domain name ### If you are self-hosted at home: fix ports forwarding Check that you are getting access to the server by using its public IP (you can find at [https://ip.yunohost.org](https://ip.yunohost.org). If this does not work: - Make sure you have [set up forwarding](/admin/get_started/post_install/port_forwarding) - Some ISP routers do not support *hairpinning*, which prevents you from reaching your server by its domain name from within your local network. If so, you can use one of the following workaround: - use a cellular connection (4/5G) - tweak your `/etc/hosts` file on each of your client devices - add YunoHost's local IP as DNS resovler in your router (usually in the DHCP section) and open port `53` (UDP) in YunoHost's firewall, making sure to **not** enable UPnP forwarding. (Do **not** open port 53 on your router) ### Configure DNS records :::tip This is not a problem if you are using a domain from `nohost.me`, `noho.st` or `ynh.fr`) ::: You have to configure your [DNS records](/admin/get_started/post_install/dns_config) (at least `A` records, and `AAAA` if you have an IPv6 connection). You can check that the DNS records are correct by comparing the results given by [this service](https://www.whatsmydns.net/) with the [IP given by our service](https://ip.yunohost.org). ### Other probable causes - You domain `noho.st`, `nohost.me`, or `ynh.fr` is unreachable following a failure on YunoHost's infrastructure. Check the [forum](https://forum.yunohost.org/) for announcements or people posting about the same issue. - Your domain name may be expired. Check that on your registrar's client panel, or by using the command `whois yourdomain.tld`. - You have a dynamic IP address. In that case, you need to set up a script or a client that takes care of regularly update it. Refer to the page on [DNS with a dynamic IP](/admin/tutorials/domains/dns_dynamicip) to see how. You can also use a domain `nohost.me`, `noho.st` or `ynh.fr` that includes this features. ## You are getting a certificate error that prevents you from reaching the webadmin - A certificate error may be displayed if you have made a typo in the address bar of your browser. - If you have just installed your server, or just installed a new domain, it uses a self-signed certificate. In that case, it is possible and understandable to add a *temporary* security exception so that you can [install a Let's Encrypt certificate](/admin/domains/certificate), provided you have a secure Internet connection. ## You have access via SSH but not via the webadmin, or inversely ### You are trying to log in with SSH as `root` instead of `admin` user By default, SSH connection has to be made as `admin`. It possible to log into the server as `root` *only from the local network of the server*. If your server is a VPS, the web console or VNC provided by VPS providers may work. If you are running `yunohost` commands in the CLI as `admin`, you have to call them with `sudo` before (for example `sudo yunohost user list`). You can also become `root` by running `sudo su`. ### You have been temporarily banned Your YunoHost server includes a service, Fail2ban, which automatically bans IPs that fail several times in a row to log in. In some cases it can be software (e.g. Nextcloud client) that are confifured with an old password, or a user who has the same IP as you have. If you have been banned while trying to access a web page, and only web pages are unreachable, you may have access to your server via SSH. Similarly, if you have been banned from SSH, webadmin access may work. If you have been banned from both SSH and webadmin, you can try to reach your server through another IP address. For example through the cellular network of your phone, a VPN, Tor, or another proxy. See also : [unban an IP on Fail2Ban](/admin/troubleshooting/fail2ban) :::note Ban are usually 10 to 12-minute-long, and on IPv4 only. ::: ### NGINX web server is broken Maybe the NGINX web server is out of order. You can check that [trough SSH](/admin/command_line) with the command `yunohost service status nginx`. If it is failing, check that its configuration is correct by running `nginx -t`. If it is indeed broken, it may be due to the installation or removal of a low-quality app... If you need support, [ask for it](/community/help). The NGINX or SSH servers may have been killed due to a lack of storage space, RAM, or swap. - Try restarting the service with `systemctl restart nginx`. - You can check used storage with `df -h`. If one of your partitions is full, you need to identify what fills it and make room. You can use `ncdu` command (install it with `apt install ncdu`) to browse from the root directory: `ncdu /` - You can check RAM and swap usage with `free -h`. Depending on the result, it may be necessary to optimize your server to use less RAM (removal of heavy or unused apps...), add more RAM or add a swap file. ### Your server is reachable by IPv6, but not IPv4, or inversely You can check that by `ping`ing it: ```bash ping -4 yourdomain.tld # or its IPv4 ping -6 yourdomain.tld # or its IPv6 ``` If one of the two is working, use it to connect by SSH or the webadmin. If none are working, you need to resolv your connection issue. In some cases, an update of your router may have enabled IPv6 and DNS configuration may be disrupted. ## Webadmin is working, but some web apps are returning 502 errors It is highly probable that the underlying service for these apps is failing (e.g. PHP apps requiring `php7.0-fpm` or `php7.3-fpm`). You can then try to restart the services, and/or ask for [help](/community/help) ## You have lost your admin password, or the password is seemingly wrong If you can reach the webadmin login page (force reload with `CTRL + F5` to be sure), and you cannot log in, your password is probably wrong. If yoy are sure of your passord, it may be due to the `slapd` service failing. If that's the case, log into the server by SSH as `root`. - If your server is at home, you most likely have access to the local network. From this network, you can follow the [SSH instructions](/admin/command_line)`. - If your server is a VPS, your provider may offer a web console. Once logged in, you have to check the state of the service with `yunohost service status slapd` and/or reset your admin password with `yunohost tools adminpw`. If this is still failing, on a VPS you may be able to reboot in rescue mode. Do not hesitate to ask for [help](/community/help) :::warning To be completed ::: ## Your VPN expired or does not connect any more If you have a VPN with fixed IP, maybe it has expired, or the provider's infrastructure is failing. In that case, contact your VPN provider to renew it and update the parameters of the VPN Client app. Meanwhile, try reaching your server if it is at home, by: - its local IP, using one of the method listed [on the corresponding page](/admin/get_started/post_install/find_ip) - reaching it at `yunohost.local`, assuming your client supports the Bonjour protocol (or `yunohost-2.local`, etc. depending on how many YunoHost servers are on your network) :::warning To be completed ::: ## Your server does not boot In some cases your server may be stuck at boot. It may come from a new, buggy, kernel. Try changing to another kernel on the boot screen (via VNC for VPS). If you are in "rescue" mode with `grub`, it may be due a misconfiguration of `grub`, or a corrupted drive. In that case, access the storage drive from another system (your provider's "rescue" mode, live USB drive, read the SD or drive on another computer) and try to check partitions integrity with `smartctl`, `fsck`, and `mount`. If disks are corrupted or hard to mount, you have to save your data and maybe reformat, reinstall, and/or change the drive. If you succeed in mounting the drive, you can use `systemd-nspawn` to access its database. Otherwise, run `grub-update`, `grub-install` again with `chroot` or with `systemd-nspawn`. ## VNC or screen access does not work It may be due hardware issue on your server, or with the hypervisor if it is on a VPS. If you are renting your server, contact the support of your provider. Otherwise, try fixing your machine by replacing failing components. ================================================ FILE: docs/admin/50.troubleshooting/20.ipv6.mdx ================================================ --- title: Setting up IPv6 hide_table_of_contents: true --- IPv6 may work out of the box in many cases. But in some cases or some specific provider, you may need to tweak things manually to enable IPv6. ## With a VPS from OVH OVH gives one IPv4 address and one IPv6 address for VPS but by default, only IPv4 is OK. Please check [The OVH documentation](https://docs.ovh.com/gb/en/vps/configuring-ipv6/). ### Configure the DNS server Also check [the documentation for subdomains](/admin/tutorials/domains/dns_subdomains). ### Configure the server On the OVH panel, you will copy 3 elements: - the IPv6 address - the IPv6 gateway address - the IPv6 prefix. On OVH's VPS SSD, prefixes are `/128` because you have only *one* IPv6 address. On your VPS, create a backup of the network configuration with : `cp /etc/network/interfaces ~/interfaces` in home directory. Then, you can edit the configuration file (`/etc/network/interfaces`) with the following. :::note In this example, it is assumed that your network interface is `eth0`. If it's different (check with `ip a`) you need to adapt the example below. ::: ```text iface eth0 inet6 static address
This is the documentation for YunoHost,an **operating system** aiming to **simplify server administration**!
{' '}
{' '}
## Do's
### Be courteous and patient
Help in the chatrooms or on the forum is given by our users and contributors, all volunteers. You may be in a hurry, you may be exhausted by fruitless trials or overwhelmed by unpleasant emotions... Have a break, have a sip of your preferred soothing beverage, breathe and once you've recovered your composure continue reading. We need you in a good mindset to help you.
### Ask in the right place
Support is only available on [the forum](https://forum.yunohost.org?target=_blank) or our [chatrooms](/community/chat_rooms).
We are also on Mastodon, but we do not offer help on this platform.
On the forum, make sure you open your request in the proper category, to maximize your chances of receiving appropriate help:
- [Support](https://forum.yunohost.org/c/support/6?target=_blank) for issues when setting up or using YunoHost itself;
- [Support apps](https://forum.yunohost.org/c/apps/11?target=_blank) for issues when setting up or using apps.
To allow us to help you on the forum, you absolutely need to fill in the Support request template, it will be displayed upon message creation.
### Explain the context
Your request needs to be stated in a complete but concise way. Explain plainly what you want to achieve and in what manner it is not working for you.
Don't hesitate to provide any information that may be relevant, even things that may seem obvious, as the person(s) who will be trying to help you may need this information.
### Show errors and logs
This is absolutely paramount if YunoHost or a command fails. It always explains why, through a single error code or a full wall of seemingly illegible text.
For the latter, YunoHost provides green "Share with YunoPaste" buttons when something fails or in the Services page of the webadmin. Click on it, it will open a new web page, and you can then share its URL.
We recommend that you share these logs in their entirety using the link generated by YunoPaste.
Avoid extracts from the logs, as decisive information may be elsewhere.
Also, avoid copying and pasting them into the forum, as it's unpleasant to go through them like that, share the YunoPaste link.
This is coupled to the 'sources' resource in the manifest.toml
### Sources`ynh_setup_source`
Download, check integrity, uncompress and patch the source from app.src
**Usage**: `ynh_setup_source --dest_dir=dest_dir [--source_id=source_id] [--keep="file1 file2"] [--full_replace]`
**Arguments**:
- `-d`, `--dest_dir=`: Directory where to setup sources
- `-s`, `--source_id=`: Name of the source, defaults to `main` (when the sources resource exists in manifest.toml) or (legacy) `app` otherwise
- `-k`, `--keep=`: Space-separated list of files/folders that will be backup/restored in $dest_dir, such as a config file you don't want to overwrite. For example 'conf.json secrets.json logs' (no trailing `/` for folders)
- `-r`, `--full_replace=`: Remove previous sources before installing new sources (can be 1 or 0, default to 0)
**Details**:
##### New 'sources' resources
(See also the resources documentation which may be more complete?)
This helper will read infos from the 'sources' resources in the manifest.toml of the app
and expect a structure like:
```toml
[resources.sources]
[resources.sources.main]
url = "https://some.address.to/download/the/app/archive"
sha256 = "0123456789abcdef" # The sha256 sum of the asset obtained from the URL
```
##### Optional flags
```text
format = "tar.gz"/xz/bz2 # automatically guessed from the extension of the URL, but can be set explicitly. Will use `tar` to extract
"zip" # automatically guessed from the extension of the URL, but can be set explicitly. Will use `unzip` to extract
"docker" # useful to extract files from an already-built docker image (instead of rebuilding them locally). Will use `docker-image-extract` to extract
"whatever" # an arbitrary value, not really meaningful except to imply that the file won't be extracted
in_subdir = true # default, there's an intermediate subdir in the archive before accessing the actual files
false # sources are directly in the archive root
n # (special cases) an integer representing a number of subdirs levels to get rid of
extract = true # default if file is indeed an archive such as .zip, .tar.gz, .tar.bz2, ...
= false # default if file 'format' is not set and the file is not to be extracted because it is not an archive but a script or binary or whatever asset.
# in which case the file will only be `mv`ed to the location possibly renamed using the `rename` value
rename = "whatever_your_want" # to be used for convenience when `extract` is false and the default name of the file is not practical
platform = "linux/amd64" # (defaults to "linux/$YNH_ARCH") to be used in conjonction with `format = "docker"` to specify which architecture to extract for
```
You may also define assets url and checksum per-architectures such as:
```toml
[resources.sources]
[resources.sources.main]
amd64.url = "https://some.address.to/download/the/app/archive/when/amd64"
amd64.sha256 = "0123456789abcdef"
armhf.url = "https://some.address.to/download/the/app/archive/when/armhf"
armhf.sha256 = "fedcba9876543210"
```
In which case `ynh_setup_source --dest_dir="$install_dir"` will automatically pick the appropriate source depending on the arch
The helper will:
- Download the specific URL if there is no local archive
- Check the integrity with the specific sha256 sum
- Uncompress the archive to `$dest_dir`.
- If `in_subdir` is true, the first level directory of the archive will be removed.
- If `in_subdir` is a numeric value, the N first level directories will be removed.
- Patches named `sources/patches/${src_id}-*.patch` will be applied to `$dest_dir`
- Extra files in `sources/extra_files/$src_id` will be copied to dest_dir
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/sources#L85)
These allow to install specific version of the technology required to run some apps
## DatabasesThis is coupled to the 'database' resource in the manifest.toml - at least for mysql/postgresql. Mongodb/redis may have better integration in the future.
### Mysql`ynh_mysql_connect_as`
Open a connection as a user
**Usage**: `ynh_mysql_connect_as --user=user --password=password [--database=database]`
**Arguments**:
- `-u`, `--user=`: the user name to connect as
- `-p`, `--password=`: the user password
- `-d`, `--database=`: the database to connect to
**Examples**:
- `ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"`
- `ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql`
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mysql#L33)
`ynh_mysql_execute_as_root`
Execute a command as root user
**Usage**: `ynh_mysql_execute_as_root --sql=sql [--database=database]`
**Arguments**:
- `-s`, `--sql=`: the SQL command to execute
- `-d`, `--database=`: the database to connect to
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mysql#L54)
`ynh_mysql_execute_file_as_root`
Execute a command from a file as root user
**Usage**: `ynh_mysql_execute_file_as_root --file=file [--database=database]`
**Arguments**:
- `-f`, `--file=`: the file containing SQL commands
- `-d`, `--database=`: the database to connect to
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mysql#L78)
`ynh_mysql_dump_db`
Dump a database
**Usage**: `ynh_mysql_dump_db --database=database`
**Arguments**:
- `-d`, `--database=`: the database name to dump
**Returns**: The mysqldump output
**Example**: `ynh_mysql_dump_db --database=roundcube > ./dump.sql`
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mysql#L146)
`ynh_psql_connect_as`
Open a connection as a user
**Usage**: `ynh_psql_connect_as --user=user --password=password [--database=database]`
**Arguments**:
- `-u`, `--user=`: the user name to connect as
- `-p`, `--password=`: the user password
- `-d`, `--database=`: the database to connect to
**Examples**:
- `ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"`
- `ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql`
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/postgresql#L36)
`ynh_psql_execute_as_root`
Execute a command as root user
**Usage**: `ynh_psql_execute_as_root --sql=sql [--database=database]`
**Arguments**:
- `-s`, `--sql=`: the SQL command to execute
- `-d`, `--database=`: the database to connect to
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/postgresql#L57)
`ynh_psql_execute_file_as_root`
Execute a command from a file as root user
**Usage**: `ynh_psql_execute_file_as_root --file=file [--database=database]`
**Arguments**:
- `-f`, `--file=`: the file containing SQL commands
- `-d`, `--database=`: the database to connect to
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/postgresql#L82)
`ynh_psql_dump_db`
Dump a database
**Usage**: `ynh_psql_dump_db --database=database`
**Arguments**:
- `-d`, `--database=`: the database name to dump
**Returns**: the psqldump output
**Example**: `ynh_psql_dump_db 'roundcube' > ./dump.sql`
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/postgresql#L153)
`ynh_psql_database_exists`
Check if a psql database exists
**Usage**: `ynh_psql_database_exists --database=database
| exit: Return 1 if the database doesn't exist, 0 otherwise`
**Arguments**:
- `-d`, `--database=`: the database for which to check existence
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/postgresql#L210)
`ynh_mongo_exec`
Execute a mongo command
example: ynh_mongo_exec --command='db.getMongo().getDBNames().indexOf("wekan")'
example: ynh_mongo_exec --command="db.getMongo().getDBNames().indexOf(\"wekan\")"
**Usage**: `ynh_mongo_exec [--user=user] [--password=password] [--authenticationdatabase=authenticationdatabase] [--database=database] [--host=host] [--port=port] --command="command" [--eval]`
**Arguments**:
- `-u`, `--user=`: The user name to connect as
- `-p`, `--password=`: The user password
- `-d`, `--authenticationdatabase=`: The authenticationdatabase to connect to
- `-d`, `--database=`: The database to connect to
- `-h`, `--host=`: The host to connect to
- `-P`, `--port=`: The port to connect to
- `-c`, `--command=`: The command to evaluate
- `-e`, `--eval`: Evaluate instead of execute the command.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L35)
`ynh_mongo_dump_db`
Dump a database
**Usage**: `ynh_mongo_dump_db --database=database`
**Arguments**:
- `-d`, `--database=`: The database name to dump
**Returns**: the mongodump output
**Example**: `ynh_mongo_dump_db --database=wekan > ./dump.bson`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L144)
`ynh_mongo_database_exists`
Check if a mongo database exists
**Usage**: `ynh_mongo_database_exists --database=database
| exit: Return 1 if the database doesn't exist, 0 otherwise`
**Arguments**:
- `-d`, `--database=`: The database for which to check existence
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L189)
`ynh_mongo_restore_db`
Restore a database
**Usage**: `ynh_mongo_restore_db --database=database`
**Arguments**:
- `-d`, `--database=`: The database name to restore
**Example**: `ynh_mongo_restore_db --database=wekan < ./dump.bson`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L212)
`ynh_mongo_setup_db`
Create a database, a user and its password. Then store the password in the app's config
**Usage**: `ynh_mongo_setup_db --db_user=user --db_name=name [--db_pwd=pwd]`
**Arguments**:
- `-u`, `--db_user=`: Owner of the database
- `-n`, `--db_name=`: Name of the database
- `-p`, `--db_pwd=`: Password of the database. If not provided, a password will be generated
**Details**:
After executing this helper, the password of the created database will be available in $db_pwd
It will also be stored as "mongopwd" into the app settings.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L255)
`ynh_mongo_remove_db`
Remove a database if it exists, and the associated user
**Usage**: `ynh_mongo_remove_db --db_user=user --db_name=name`
**Arguments**:
- `-u`, `--db_user=`: Owner of the database
- `-n`, `--db_name=`: Name of the database
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L283)
`ynh_install_mongo`
Install MongoDB and integrate MongoDB service in YunoHost
**Usage**: `ynh_install_mongo [--mongo_version=mongo_version]`
**Arguments**:
- `-m`, `--mongo_version=`: Version of MongoDB to install
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L308)
`ynh_remove_mongo`
Remove MongoDB
Only remove the MongoDB service integration in YunoHost for now
if MongoDB package as been removed
**Usage**: `ynh_remove_mongo`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/mongodb#L351)
`ynh_redis_get_free_db`
get the first available redis database
**Usage**: `ynh_redis_get_free_db`
**Returns**: the database number to use
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/redis#L25)
`ynh_redis_remove_db`
Create a master password and set up global settings
Please always call this script in install and restore scripts
**Usage**: `ynh_redis_remove_db database`
**Arguments**:
- `database`: the database to erase
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/redis#L52)
`ynh_add_config`
Create a dedicated config file from a template
**Usage**: `ynh_add_config --template="template" --destination="destination"`
**Arguments**:
- `-t`, `--template=`: Template config file to use
- `-d`, `--destination=`: Destination of the config file
- `-j`, `--jinja`: Use jinja template instead of the simple `__MY_VAR__` templating format
**Examples**:
- `ynh_add_config --template=".env" --destination="$install_dir/.env" # (use the template file "conf/.env" from the app's package)`
- `ynh_add_config --jinja --template="config.j2" --destination="$install_dir/config" # (use the template file "conf/config.j2" from the app's package)`
**Details**:
The template can be by default the name of a file in the conf directory
of a YunoHost Package, a relative path or an absolute path.
The helper will use the template `template` to generate a config file
`destination` by replacing the following keywords with global variables
that should be defined before calling this helper :
```
__PATH__ by $path_url
__NAME__ by $app
__NAMETOCHANGE__ by $app
__USER__ by $app
__FINALPATH__ by $final_path
__PHPVERSION__ by $YNH_PHP_VERSION (packaging v1 only, packaging v2 uses phpversion setting implicitly set by apt resource)
__YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH
```
And any dynamic variables that should be defined before calling this helper like:
```
__DOMAIN__ by $domain
__APP__ by $app
__VAR_1__ by $var_1
__VAR_2__ by $var_2
```
##### When --jinja is enabled
This option is meant for advanced use-cases where the "simple" templating
mode ain't enough because you need conditional blocks or loops.
For a full documentation of jinja's syntax you can refer to:
https://jinja.palletsprojects.com/en/3.1.x/templates/
Note that in YunoHost context, all variables are from shell variables and therefore are strings
##### Keeping track of manual changes by the admin
The helper will verify the checksum and backup the destination file
if it's different before applying the new template.
And it will calculate and store the destination file checksum
into the app settings when configuration is done.
Requires YunoHost version 4.1.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/templating#L74)
`ynh_read_var_in_file`
Get a value from heterogeneous file (yaml, json, php, python...)
**Usage**: `ynh_read_var_in_file --file=PATH --key=KEY`
**Arguments**:
- `-f`, `--file=`: the path to the file
- `-k`, `--key=`: the key to get
- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file)
**Details**:
This helpers match several var affectation use case in several languages
We don't use jq or equivalent to keep comments and blank space in files
This helpers work line by line, it is not able to work correctly
if you have several identical keys in your files
Example of line this helpers can managed correctly
.yml
title: YunoHost documentation
email: 'yunohost@yunohost.org'
.json
"theme": "colib'ris",
"port": 8102
"some_boolean": false,
"user": null
.ini
some_boolean = On
action = "Clear"
port = 20
.php
$user=
user => 20
.py
USER = 8102
user = 'https://donate.local'
CUSTOM['user'] = 'YunoHost'
Requires YunoHost version 4.3 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/templating#L240)
`ynh_write_var_in_file`
Set a value into heterogeneous file (yaml, json, php, python...)
**Usage**: `ynh_write_var_in_file --file=PATH --key=KEY --value=VALUE`
**Arguments**:
- `-f`, `--file=`: the path to the file
- `-k`, `--key=`: the key to set
- `-v`, `--value=`: the value to set
- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file)
**Details**:
Requires YunoHost version 4.3 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/templating#L318)
`ynh_add_nginx_config`
Create a dedicated nginx config
**Usage**: `ynh_add_nginx_config`
**Details**:
This will use a template in `../conf/nginx.conf`
See the documentation of `ynh_add_config` for a description of the template
format and how placeholders are replaced with actual variables.
Additionally, ynh_add_nginx_config will replace:
- `#sub_path_only` by empty string if `path_url` is not `'/'`
- `#root_path_only` by empty string if `path_url` *is* `'/'`
This allows to enable/disable specific behaviors dependenging on the install
location
Requires YunoHost version 4.1.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/nginx#L37)
`ynh_remove_nginx_config`
Remove the dedicated nginx config
**Usage**: `ynh_remove_nginx_config`
**Details**:
Requires YunoHost version 2.7.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/nginx#L64)
`ynh_change_url_nginx_config`
Regen the nginx config in a change url context
**Usage**: `ynh_change_url_nginx_config`
**Details**:
Requires YunoHost version 11.1.9 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/nginx#L74)
`ynh_add_fpm_config`
Create a dedicated PHP-FPM config
**Usage**: `ynh_add_fpm_config`
**Details**:
Case 1 (recommended) : your provided a snippet conf/extra_php-fpm.conf
The actual PHP configuration will be automatically generated,
and your extra_php-fpm.conf will be appended (typically contains PHP upload limits)
The resulting configuration will be deployed to the appropriate place, /etc/php/$phpversion/fpm/pool.d/$app.conf
Performance-related options in the PHP conf, such as :
pm.max_children, pm.start_servers, pm.min_spare_servers pm.max_spare_servers
are computed from two parameters called "usage" and "footprint" which can be set to low/medium/high. (cf details below)
If you wish to tweak those, please initialize the settings `fpm_usage` and `fpm_footprint`
*prior* to calling this helper. Otherwise, "low" will be used as a default for both values.
Otherwise, if you want the user to have control over these, we encourage to create a config panel
(which should ultimately be standardized by the core ...)
Case 2 (deprecate) : you provided an entire conf/php-fpm.conf
The configuration will be hydrated, replacing __FOOBAR__ placeholders with $foobar values, etc.
The resulting configuration will be deployed to the appropriate place, /etc/php/$phpversion/fpm/pool.d/$app.conf
----------------------
fpm_footprint: Memory footprint of the service (low/medium/high).
low - Less than 20 MB of RAM by pool.
medium - Between 20 MB and 40 MB of RAM by pool.
high - More than 40 MB of RAM by pool.
N - Or you can specify a quantitative footprint as MB by pool (use watch -n0.5 ps -o user,cmd,%cpu,rss -u APP)
fpm_usage: Expected usage of the service (low/medium/high).
low - Personal usage, behind the SSO.
medium - Low usage, few people or/and publicly accessible.
high - High usage, frequently visited website.
The footprint of the service will be used to defined the maximum footprint we can allow, which is half the maximum RAM.
So it will be used to defined 'pm.max_children'
A lower value for the footprint will allow more children for 'pm.max_children'. And so for
'pm.start_servers', 'pm.min_spare_servers' and 'pm.max_spare_servers' which are defined from the
value of 'pm.max_children'
NOTE: 'pm.max_children' can't exceed 4 times the number of processor's cores.
The usage value will defined the way php will handle the children for the pool.
A value set as 'low' will set the process manager to 'ondemand'. Children will start only if the
service is used, otherwise no child will stay alive. This config gives the lower footprint when the
service is idle. But will use more proc since it has to start a child as soon it's used.
Set as 'medium', the process manager will be at dynamic. If the service is idle, a number of children
equal to pm.min_spare_servers will stay alive. So the service can be quick to answer to any request.
The number of children can grow if needed. The footprint can stay low if the service is idle, but
not null. The impact on the proc is a little bit less than 'ondemand' as there's always a few
children already available.
Set as 'high', the process manager will be set at 'static'. There will be always as many children as
'pm.max_children', the footprint is important (but will be set as maximum a quarter of the maximum
RAM) but the impact on the proc is lower. The service will be quick to answer as there's always many
children ready to answer.
Requires YunoHost version 4.1.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/php#L88)
`ynh_remove_fpm_config`
Remove the dedicated PHP-FPM config
**Usage**: `ynh_remove_fpm_config`
**Details**:
Requires YunoHost version 2.7.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/php#L223)
`ynh_add_systemd_config`
Create a dedicated systemd config
**Usage**: `ynh_add_systemd_config [--service=service] [--template=template]`
**Arguments**:
- `-s`, `--service=`: Service name (optionnal, `$app` by default)
- `-t`, `--template=`: Name of template file (optionnal, this is 'systemd' by default, meaning `../conf/systemd.service` will be used as template)
**Details**:
This will use the template `../conf/`ynh_remove_systemd_config`
Remove the dedicated systemd config
**Usage**: `ynh_remove_systemd_config [--service=service]`
**Arguments**:
- `-s`, `--service=`: Service name (optionnal, $app by default)
**Details**:
Requires YunoHost version 2.7.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/systemd#L56)
`ynh_systemd_action`
Start (or other actions) a service, print a log in case of failure and optionnaly wait until the service is completely started
**Usage**: `ynh_systemd_action [--service_name=service_name] [--action=action] [ [--line_match="line to match"] [--log_path=log_path] [--timeout=300] [--length=20] ]`
**Arguments**:
- `-n`, `--service_name=`: Name of the service to start. Default : `$app`
- `-a`, `--action=`: Action to perform with systemctl. Default: start
- `-l`, `--line_match=`: Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started.
- `-p`, `--log_path=`: Log file - Path to the log file. Default : `/var/log/$app/$app.log`
- `-t`, `--timeout=`: Timeout - The maximum time to wait before ending the watching. Default : 300 seconds.
- `-e`, `--length=`: Length of the error log displayed for debugging : Default : 20
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/systemd#L85)
`ynh_add_fail2ban_config`
Create a dedicated fail2ban config (jail and filter conf files)
**Usage**: `1: ynh_add_fail2ban_config --logpath=log_file --failregex=filter [--max_retry=max_retry] [--ports=ports]
2: ynh_add_fail2ban_config --use_template`
**Arguments**:
- `-l`, `--logpath=`: Log file to be checked by fail2ban
- `-r`, `--failregex=`: Failregex to be looked for by fail2ban
- `-m`, `--max_retry=`: Maximum number of retries allowed before banning IP address - default: 3
- `-p`, `--ports=`: Ports blocked for a banned IP address - default: http,https
- `-t`, `--use_template`: Use this helper in template mode
**Details**:
This will use a template in `../conf/f2b_jail.conf` and `../conf/f2b_filter.conf`
See the documentation of `ynh_add_config` for a description of the template
format and how placeholders are replaced with actual variables.
Generally your template will look like that by example (for synapse):
```
f2b_jail.conf:
[__APP__]
enabled = true
port = http,https
filter = __APP__
logpath = /var/log/__APP__/logfile.log
maxretry = 3
```
```
f2b_filter.conf:
[INCLUDES]
before = common.conf
[Definition]
# Part of regex definition (just used to make more easy to make the global regex)
__synapse_start_line = .? \- synapse\..+ \-
# Regex definition.
failregex = ^%(__synapse_start_line)s INFO \- POST\-(\d+)\- `ynh_remove_fail2ban_config`
Remove the dedicated fail2ban config (jail and filter conf files)
**Usage**: `ynh_remove_fail2ban_config`
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/fail2ban#L148)
`ynh_use_logrotate`
Use logrotate to manage the logfile
**Usage**: `ynh_use_logrotate [--logfile=/log/file] [--specific_user=user/group]`
**Arguments**:
- `-l`, `--logfile=`: absolute path of logfile
- `-u`, `--specific_user=`: run logrotate as the specified user and group. If not specified logrotate is runned as root.
**Details**:
If no `--logfile` is provided, `/var/log/$app` will be used as default.
`logfile` can point to a directory or a file.
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logrotate#L33)
`ynh_remove_logrotate`
Remove the app's logrotate config.
**Usage**: `ynh_remove_logrotate`
**Details**:
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logrotate#L113)
`ynh_local_curl`
Curl abstraction to help with POST requests to local pages (such as installation forms)
**Usage**: `ynh_local_curl "page_uri" "key1=value1" "key2=value2" ...`
**Arguments**:
- `page_uri`: Path (relative to `$path_url`) of the page where POST data will be sent
- `key1=value1`: (Optionnal) POST key and corresponding value
- `key2=value2`: (Optionnal) Another POST key and corresponding value
- `...`: (Optionnal) More POST keys and values
**Example**: `ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2"`
**Details**:
For multiple calls, cookies are persisted between each call for the same app
`$domain` and `$path_url` should be defined externally (and correspond to the domain.tld and the /path (of the app?))
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/utils#L106)
`ynh_secure_remove`
Remove a file or a directory securely
**Usage**: `ynh_secure_remove --file=path_to_remove`
**Arguments**:
- `-f`, `--file=`: File or directory to remove
**Details**:
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/utils#L189)
`ynh_read_manifest`
Read the value of a key in a ynh manifest file
**Usage**: `ynh_read_manifest --manifest="manifest.json" --manifest_key="key"`
**Arguments**:
- `-m`, `--manifest=`: Path of the manifest to read
- `-k`, `--manifest_key=`: Name of the key to find
**Returns**: the value associate to that key
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/utils#L223)
`ynh_app_upstream_version`
Read the upstream version from the manifest or `$YNH_APP_MANIFEST_VERSION`
**Usage**: `ynh_app_upstream_version [--manifest="manifest.json"]`
**Arguments**:
- `-m`, `--manifest=`: Path of the manifest to read
**Returns**: the version number of the upstream app
**Details**:
If the `manifest` is not specified, the envvar `$YNH_APP_MANIFEST_VERSION` will be used.
The version number in the manifest is defined by ``ynh_check_app_version_changed`
Checks the app version to upgrade with the existing app version and returns:
**Usage**: `ynh_check_app_version_changed`
**Returns**: `UPGRADE_APP` if the upstream version changed, `UPGRADE_PACKAGE` otherwise.
**Details**:
This helper should be used to avoid an upgrade of an app, or the upstream part
of it, when it's not needed
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/utils#L315)
`ynh_compare_current_package_version`
Compare the current package version against another version given as an argument.
**Usage**: `ynh_compare_current_package_version --comparison (lt|le|eq|ne|ge|gt) --version `ynh_user_exists`
Check if a YunoHost user exists
**Usage**: `ynh_user_exists --username=username`
**Arguments**:
- `-u`, `--username=`: the username to check
**Returns**: 0 if the user exists, 1 otherwise.
**Example**: `ynh_user_exists 'toto' || echo "User does not exist"`
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/utils#L422)
`ynh_user_get_info`
Retrieve a YunoHost user information
**Usage**: `ynh_user_get_info --username=username --key=key`
**Arguments**:
- `-u`, `--username=`: the username to retrieve info from
- `-k`, `--key=`: the key to retrieve
**Returns**: the value associate to that key
**Example**: `mail=$(ynh_user_get_info --username="toto" --key=mail)`
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/utils#L443)
`ynh_user_list`
Get the list of YunoHost users
**Usage**: `ynh_user_list`
**Returns**: one username per line as strings
**Example**: `for u in $(ynh_user_list); do ... ; done`
**Details**:
Requires YunoHost version 2.4.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/utils#L463)
`ynh_app_setting_get`
Get an application setting
**Usage**: `ynh_app_setting_get --app=app --key=key`
**Arguments**:
- `-a`, `--app=`: the application id
- `-k`, `--key=`: the setting to get
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/setting#L28)
`ynh_app_setting_set`
Set an application setting
**Usage**: `ynh_app_setting_set --app=app --key=key --value=value`
**Arguments**:
- `-a`, `--app=`: the application id
- `-k`, `--key=`: the setting name to set
- `-v`, `--value=`: the setting value to set
**Details**:
When choosing the setting key's name, note that including the following keywords will make the associated setting's value appear masked in the debug logs (cf. [related code](https://github.com/YunoHost/yunohost/blob/216210d5e97070b85c96ebb4548c6abf36987771/src/log.py#L571)): `pwd`, `pass`, `passwd`, `password`, `passphrase`, `secret\w*` (regex), `\w+key` (regex), `token`, `PASSPHRASE`
This is meant to allow sharing the logs while preserving confidential data, but having this in mind is useful would you expect to see those values while debugging your scripts.
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/setting#L53)
`ynh_app_setting_set_default`
Set an application setting but only if the "$key" variable ain't set yet
**Usage**: `ynh_app_setting_set_default --app=app --key=key --value=value`
**Arguments**:
- `-a`, `--app=`: the application id
- `-k`, `--key=`: the setting name to set
- `-v`, `--value=`: the default setting value to set
**Details**:
Note that it doesn't just define the setting but ALSO define the $foobar variable
Hence it's meant as a replacement for this legacy overly complex syntax:
```
if [ -z "${foo:-}" ]
then
foo="bar"
ynh_app_setting_set --key="foo" --value="$foo"
fi
```
Requires YunoHost version 11.1.16 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/setting#L88)
`ynh_app_setting_delete`
Delete an application setting
**Usage**: `ynh_app_setting_delete --app=app --key=key`
**Arguments**:
- `-a`, `--app=`: the application id
- `-k`, `--key=`: the setting to delete
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/setting#L113)
`ynh_string_random`
Generate a random string
**Usage**: `ynh_string_random [--length=string_length]`
**Arguments**:
- `-l`, `--length=`: the string length to generate (default: 24)
- `-f`, `--filter=`: the kind of characters accepted in the output (default: 'A-Za-z0-9')
**Returns**: the generated string
**Example**: `pwd=$(ynh_string_random --length=8)`
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/string#L31)
`ynh_replace_string`
Substitute/replace a string (or expression) by another in a file
**Usage**: `ynh_replace_string --match_string=match_string --replace_string=replace_string --target_file=target_file`
**Arguments**:
- `-m`, `--match_string=`: String to be searched and replaced in the file
- `-r`, `--replace_string=`: String that will replace matches
- `-f`, `--target_file=`: File in which the string will be replaced.
**Details**:
As this helper is based on sed command, regular expressions and references to
sub-expressions can be used (see sed manual page for more information)
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/string#L56)
`ynh_replace_special_string`
Substitute/replace a special string by another in a file
**Usage**: `ynh_replace_special_string --match_string=match_string --replace_string=replace_string --target_file=target_file`
**Arguments**:
- `-m`, `--match_string=`: String to be searched and replaced in the file
- `-r`, `--replace_string=`: String that will replace matches
- `-t`, `--target_file=`: File in which the string will be replaced.
**Details**:
This helper will use ynh_replace_string, but as you can use special
characters, you can't use some regular expressions and sub-expressions.
Requires YunoHost version 2.7.7 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/string#L87)
`ynh_backup`
Add a file or a directory to the list of paths to backup
**Usage**: `ynh_backup --src_path=src_path [--dest_path=dest_path] [--is_big] [--not_mandatory]`
**Arguments**:
- `-s`, `--src_path=`: file or directory to bind or symlink or copy. it shouldn't be in the backup dir.
- `-d`, `--dest_path=`: destination file or directory inside the backup dir
- `-b`, `--is_big`: Indicate data are big (mail, video, image ...)
- `-m`, `--not_mandatory`: Indicate that if the file is missing, the backup can ignore it.
**Details**:
This helper can be used both in a system backup hook, and in an app backup script
`ynh_backup` writes `src_path` and the relative `dest_path` into a CSV file, and it
creates the parent destination directory
If `dest_path` is ended by a slash it complete this path with the basename of `src_path`.
Example in the context of a WordPress app :
```
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"
# => This line will be added into CSV file
# "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf"
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/nginx.conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf"
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf"
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf"
#Deprecated usages (maintained for retro-compatibility)
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "${backup_dir}/conf/nginx.conf"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf"
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/"
# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf"
```
How to use `--is_big`:
`--is_big` is used to specify that this part of the backup can be quite huge.
So, you don't want that your package does backup that part during ynh_backup_before_upgrade.
In the same way, an user may doesn't want to backup this big part of the app for
each of his backup. And so handle that part differently.
As this part of your backup may not be done, your restore script has to handle it.
In your restore script, use `--not_mandatory` with `ynh_restore_file`
As well in your remove script, you should not remove those data ! Or an user may end up with
a failed upgrade restoring an app without data anymore !
To have the benefit of `--is_big` while doing a backup, you can whether set the environement
variable `BACKUP_CORE_ONLY` to 1 (`BACKUP_CORE_ONLY=1`) before the backup command. It will affect
only that backup command.
Or set the config `do_not_backup_data` to 1 into the `settings.yml` of the app. This will affect
all backups for this app until the setting is removed.
Requires YunoHost version 2.4.0 or higher.
Requires YunoHost version 3.5.0 or higher for the argument `--not_mandatory`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/backup#L82)
`ynh_restore`
Restore all files that were previously backuped in a core backup script or app backup script
**Usage**: `ynh_restore`
**Details**:
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/backup#L197)
`ynh_restore_file`
Restore a file or a directory
**Usage**: `ynh_restore_file --origin_path=origin_path [--dest_path=dest_path] [--not_mandatory]`
**Arguments**:
- `-o`, `--origin_path=`: Path where was located the file or the directory before to be backuped or relative path to $YNH_CWD where it is located in the backup archive
- `-d`, `--dest_path=`: Path where restore the file or the dir. If unspecified, the destination will be `ORIGIN_PATH` or if the `ORIGIN_PATH` doesn't exist in the archive, the destination will be searched into `backup.csv`
- `-m`, `--not_mandatory`: Indicate that if the file is missing, the restore process can ignore it.
**Examples**:
- `ynh_restore_file -o "/etc/nginx/conf.d/$domain.d/$app.conf"`
- `You can also use relative paths:`
- `ynh_restore_file -o "conf/nginx.conf"`
**Details**:
Use the registered path in backup_list by ynh_backup to restore the file at the right place.
If `DEST_PATH` already exists and is lighter than 500 Mo, a backup will be made in
`/var/cache/yunohost/appconfbackup/`. Otherwise, the existing file is removed.
if `apps/$app/etc/nginx/conf.d/$domain.d/$app.conf` exists, restore it into
`/etc/nginx/conf.d/$domain.d/$app.conf`
if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into
`/etc/nginx/conf.d/$domain.d/$app.conf`
Requires YunoHost version 2.6.4 or higher.
Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/backup#L256)
`ynh_store_file_checksum`
Calculate and store a file checksum into the app settings
**Usage**: `ynh_store_file_checksum --file=file`
**Arguments**:
- `-f`, `--file=`: The file on which the checksum will performed, then stored.
**Details**:
$app should be defined when calling this helper
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/backup#L323)
`ynh_backup_if_checksum_is_different`
Verify the checksum and backup the file if it's different
**Usage**: `ynh_backup_if_checksum_is_different --file=file`
**Arguments**:
- `-f`, `--file=`: The file on which the checksum test will be perfomed.
**Returns**: the name of a backup file, or nothing
**Details**:
This helper is primarily meant to allow to easily backup personalised/manually
modified config files.
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/backup#L374)
`ynh_delete_file_checksum`
Delete a file checksum from the app settings
**Usage**: `ynh_delete_file_checksum --file=file`
**Arguments**:
- `-f`, `--file=`: The file for which the checksum will be deleted
**Details**:
$app should be defined when calling this helper
Requires YunoHost version 3.3.1 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/backup#L413)
`ynh_die`
Print a message to stderr and exit
**Usage**: `ynh_die --message=MSG [--ret_code=RETCODE]`
**Arguments**:
- `-m`, `--message=`: Message to display
- `-c`, `--ret_code=`: Exit code to exit with
**Details**:
Requires YunoHost version 2.4.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L28)
`ynh_print_info`
Display a message in the 'INFO' logging category
**Usage**: `ynh_print_info --message="Some message"`
**Arguments**:
- `-m`, `--message=`: Message to display
**Details**:
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L48)
`ynh_print_warn`
Print a warning on stderr
**Usage**: `ynh_print_warn --message="Text to print"`
**Arguments**:
- `-m`, `--message=`: The text to print
**Details**:
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L74)
`ynh_print_err`
Print an error on stderr
**Usage**: `ynh_print_err --message="Text to print"`
**Arguments**:
- `-m`, `--message=`: The text to print
**Details**:
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L91)
`ynh_exec_err`
Execute a command and print the result as an error
**Usage**: `ynh_exec_err your command and args`
**Arguments**:
- `command`: command to execute
**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_err
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L110)
`ynh_exec_warn`
Execute a command and print the result as a warning
**Usage**: `ynh_exec_warn your command and args`
**Arguments**:
- `command`: command to execute
**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L130)
`ynh_exec_warn_less`
Execute a command and force the result to be printed on stdout
**Usage**: `ynh_exec_warn_less your command and args`
**Arguments**:
- `command`: command to execute
**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L150)
`ynh_exec_quiet`
Execute a command and redirect stdout in /dev/null
**Usage**: `ynh_exec_quiet your command and args`
**Arguments**:
- `command`: command to execute
**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L170)
`ynh_exec_fully_quiet`
Execute a command and redirect stdout and stderr in /dev/null
**Usage**: `ynh_exec_quiet your command and args`
**Arguments**:
- `command`: command to execute
**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_quiet
Requires YunoHost version 3.2.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L190)
`ynh_exec_and_print_stderr_only_if_error`
Execute a command and redirect stderr in /dev/null. Print stderr on error.
**Usage**: `ynh_exec_and_print_stderr_only_if_error your command and args`
**Arguments**:
- `command`: command to execute
**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_and_print_stderr_only_if_error
Requires YunoHost version 11.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L210)
`ynh_script_progression`
Print a progress bar showing the progression of an app script
**Usage**: `ynh_script_progression --message=message [--weight=weight] [--time]`
**Arguments**:
- `-m`, `--message=`: The text to print
- `-w`, `--weight=`: The weight for this progression. This value is 1 by default. Use a bigger value for a longer part of the script.
- `-t`, `--time`: Print the execution time since the last call to this helper. Especially usefull to define weights. The execution time is given for the duration since the previous call. So the weight should be applied to this previous call.
- `-l`, `--last`: Use for the last call of the helper, to fill the progression bar.
**Details**:
Requires YunoHost version 3.5.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L270)
`ynh_return`
Return data to the YunoHost core for later processing
(to be used by special hooks like app config panel and core diagnosis)
**Usage**: `ynh_return somedata`
**Details**:
Requires YunoHost version 3.6.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/logging#L358)
`ynh_multimedia_build_main_dir`
Initialize the multimedia directory system
**Usage**: `ynh_multimedia_build_main_dir`
**Details**:
Requires YunoHost version 4.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/multimedia#L29)
`ynh_multimedia_addfolder`
Add a directory in yunohost.multimedia
**Usage**: `ynh_multimedia_addfolder --source_dir="source_dir" --dest_dir="dest_dir"`
**Arguments**:
- `-s`, `--source_dir=`: Source directory - The real directory which contains your medias.
- `-d`, `--dest_dir=`: Destination directory - The name and the place of the symbolic link, relative to "/home/yunohost.multimedia"
**Details**:
This "directory" will be a symbolic link to a existing directory.
Requires YunoHost version 4.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/multimedia#L90)
`ynh_multimedia_addaccess`
Allow an user to have an write authorisation in multimedia directories
**Usage**: `ynh_multimedia_addaccess user_name`
**Arguments**:
- `-u`, `--user_name=`: The name of the user which gain this access.
**Details**:
Requires YunoHost version 4.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/multimedia#L119)
`ynh_permission_create`
Create a new permission for the app
**Usage**: `ynh_permission_create --permission="permission" [--url="url"] [--additional_urls="second-url" [ "third-url" ]] [--auth_header=true|false]
[--allowed=group1 [ group2 ]] [--show_tile=true|false]
[--protected=true|false]`
**Arguments**:
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" already exist)
- `-u`, `--url=`: (optional) URL for which access will be allowed/forbidden. Note that if 'show_tile' is enabled, this URL will be the URL of the tile.
- `-A`, `--additional_urls=`: (optional) List of additional URL for which access will be allowed/forbidden
- `-h`, `--auth_header=`: (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application. Default is true
- `-a`, `--allowed=`: (optional) A list of group/user to allow for the permission
- `-t`, `--show_tile=`: (optional) Define if a tile will be shown in the SSO. If yes the name of the tile will be the 'label' parameter. Defaults to false for the permission different than 'main'.
- `-P`, `--protected=`: (optional) Define if this permission is protected. If it is protected the administrator won't be able to add or remove the visitors group of this permission. Defaults to 'false'.
**Details**:
Example 1: `ynh_permission_create --permission=admin --url=/admin --additional_urls=domain.tld/admin /superadmin --allowed=alice bob \
--show_tile=true`
This example will create a new permission permission with this following effect:
- A tile named "My app admin" in the SSO will be available for the users alice and bob. This tile will point to the relative url '/admin'.
- Only the user alice and bob will have the access to theses following url: /admin, domain.tld/admin, /superadmin
Example 2:
ynh_permission_create --permission=api --url=domain.tld/api --auth_header=false --allowed=visitors \
--protected=true
This example will create a new protected permission. So the admin won't be able to add/remove the visitors group of this permission.
In case of an API with need to be always public it avoid that the admin break anything.
With this permission all client will be allowed to access to the url 'domain.tld/api'.
Note that in this case no tile will be show on the SSO.
Note that the auth_header parameter is to 'false'. So no authentication header will be passed to the application.
Generally the API is requested by an application and enabling the auth_header has no advantage and could bring some issues in some case.
So in this case it's better to disable this option for all API.
If provided, 'url' or 'additional_urls' is assumed to be relative to the app domain/path if they
start with '/'. For example:
/ -> domain.tld/app
/admin -> domain.tld/app/admin
domain.tld/app/api -> domain.tld/app/api
'url' or 'additional_urls' can be treated as a PCRE (not lua) regex if it starts with "re:".
For example:
re:/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$
re:domain.tld/app/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$
Note that globally the parameter 'url' and 'additional_urls' are same. The only difference is:
- 'url' is only one url, 'additional_urls' can be a list of urls. There are no limitation of 'additional_urls'
- 'url' is used for the url of tile in the SSO (if enabled with the 'show_tile' parameter)
About the authentication header (auth_header parameter).
The SSO pass (by default) to the application theses following HTTP header (linked to the authenticated user) to the application:
- "Auth-User": username
- "Remote-User": username
- "Email": user email
Generally this feature is usefull to authenticate automatically the user in the application but in some case the application don't work with theses header and theses header need to be disabled to have the application to work correctly.
See https://github.com/YunoHost/issues/issues/1420 for more informations
Requires YunoHost version 3.7.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L83)
`ynh_permission_delete`
Remove a permission for the app (note that when the app is removed all permission is automatically removed)
**Usage**: `ynh_permission_delete --permission="permission"`
**Arguments**:
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
**Example**: `ynh_permission_delete --permission=editors`
**Details**:
Requires YunoHost version 3.7.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L161)
`ynh_permission_exists`
Check if a permission exists
**Usage**: `ynh_permission_exists --permission=permission
| exit: Return 1 if the permission doesn't exist, 0 otherwise`
**Arguments**:
- `-p`, `--permission=`: the permission to check
**Details**:
Requires YunoHost version 3.7.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L178)
`ynh_permission_url`
Redefine the url associated to a permission
**Usage**: `ynh_permission_url --permission "permission" [--url="url"] [--add_url="new-url" [ "other-new-url" ]] [--remove_url="old-url" [ "other-old-url" ]]
[--auth_header=true|false] [--clear_urls]`
**Arguments**:
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
- `-u`, `--url=`: (optional) URL for which access will be allowed/forbidden. Note that if you want to remove url you can pass an empty sting as arguments ("").
- `-a`, `--add_url=`: (optional) List of additional url to add for which access will be allowed/forbidden.
- `-r`, `--remove_url=`: (optional) List of additional url to remove for which access will be allowed/forbidden
- `-h`, `--auth_header=`: (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application
- `-c`, `--clear_urls`: (optional) Clean all urls (url and additional_urls)
**Details**:
Requires YunoHost version 3.7.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L201)
`ynh_permission_update`
Update a permission for the app
**Usage**: `ynh_permission_update --permission "permission" [--add="group" ["group" ...]] [--remove="group" ["group" ...]]
[--show_tile=true|false] [--protected=true|false]`
**Arguments**:
- `-p`, `--permission=`: the name for the permission (by default a permission named "main" already exist)
- `-a`, `--add=`: the list of group or users to enable add to the permission
- `-r`, `--remove=`: the list of group or users to remove from the permission
- `-t`, `--show_tile=`: (optional) Define if a tile will be shown in the SSO
- `-P`, `--protected=`: (optional) Define if this permission is protected. If it is protected the administrator won't be able to add or remove the visitors group of this permission.
**Details**:
Requires YunoHost version 3.7.0 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L268)
`ynh_permission_has_user`
Check if a permission has an user
**Usage**: `ynh_permission_has_user --permission=permission --user=user
| exit: Return 1 if the permission doesn't have that user or doesn't exist, 0 otherwise`
**Arguments**:
- `-p`, `--permission=`: the permission to check
- `-u`, `--user=`: the user seek in the permission
**Example**: `ynh_permission_has_user --permission=main --user=visitors`
**Details**:
Requires YunoHost version 3.7.1 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L331)
`ynh_legacy_permissions_exists`
Check if a legacy permissions exist
**Usage**: `ynh_legacy_permissions_exists
| exit: Return 1 if the permission doesn't exist, 0 otherwise`
**Details**:
Requires YunoHost version 4.1.2 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L361)
`ynh_legacy_permissions_delete_all`
Remove all legacy permissions
**Usage**: `ynh_legacy_permissions_delete_all`
**Example**: `if ynh_legacy_permissions_exists then ynh_legacy_permissions_delete_all # You can recreate the required permissions here with ynh_permission_create fi Requires YunoHost version 4.1.2 or higher.`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/permission#L381)
`ynh_package_is_installed`
Check either a package is installed or not
**Usage**: `ynh_package_is_installed --package=name`
**Arguments**:
- `-p`, `--package=`: the package name to check
**Returns**: 0 if the package is installed, 1 else.
**Example**: `ynh_package_is_installed --package=yunohost && echo "installed"`
**Details**:
Requires YunoHost version 2.2.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/apt#L71)
`ynh_install_app_dependencies`
Define and install dependencies with a equivs control file
**Usage**: `ynh_install_app_dependencies dep [dep [...]]`
**Arguments**:
- `dep`: the package name to install in dependence.
- `"dep1|dep2|…"`: You can specify alternatives. It will require to install (dep1 or dep2, etc).
**Details**:
This helper can/should only be called once per app
example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/apt#L257)
`ynh_remove_app_dependencies`
Remove fake package and its dependencies
**Usage**: `ynh_remove_app_dependencies`
**Details**:
Dependencies will removed only if no other package need them.
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/apt#L386)
`ynh_install_extra_app_dependencies`
Install packages from an extra repository properly.
**Usage**: `ynh_install_extra_app_dependencies --repo="repo" --package="dep1 dep2" [--key=key_url] [--name=name]`
**Arguments**:
- `-r`, `--repo=`: Complete url of the extra repository.
- `-p`, `--package=`: The packages to install from this extra repository
- `-k`, `--key=`: url to get the public key.
- `-n`, `--name=`: Name for the files for this repo, $app as default value.
**Details**:
Requires YunoHost version 3.8.1 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/apt#L418)
`ynh_system_user_create`
Create a system user
**Usage**: `ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] [--groups="group1 group2"]`
**Arguments**:
- `-u`, `--username=`: Name of the system user that will be create
- `-h`, `--home_dir=`: Path of the home dir for the user. Usually the final path of the app. If this argument is omitted, the user will be created without home
- `-s`, `--use_shell`: Create a user using the default login shell if present. If this argument is omitted, the user will be created with /usr/sbin/nologin shell
- `-g`, `--groups`: Add the user to system groups. Typically meant to add the user to the ssh.app / sftp.app group (e.g. for borgserver, my_webapp)
**Details**:
Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability) :
```
ynh_system_user_create --username=nextcloud
```
Create a discourse user using /var/www/discourse as home directory and the default login shell :
```
ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell
```
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/systemuser#L79)
`ynh_system_user_delete`
Delete a system user
**Usage**: `ynh_system_user_delete --username=user_name`
**Arguments**:
- `-u`, `--username=`: Name of the system user that will be create
**Details**:
Requires YunoHost version 2.6.4 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/systemuser#L121)
`ynh_exec_as`
Execute a command as another user
**Usage**: `ynh_exec_as $USER COMMAND [ARG ...]`
**Details**:
Requires YunoHost version 4.1.7 or higher.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v1.d/systemuser#L147)
This is coupled to the 'sources' resource in the manifest.toml
### Sources`ynh_setup_source`
Download, check integrity, uncompress and patch upstream sources
**Usage**: `ynh_setup_source --dest_dir=dest_dir [--source_id=source_id] [--keep="file1 file2"] [--full_replace]`
**Arguments**:
- `--dest_dir=`: Directory where to setup sources
- `--source_id=`: Name of the source, defaults to `main` (when the sources resource exists in manifest.toml) or (legacy) `app` otherwise
- `--keep=`: Space-separated list of files/folders that will be backup/restored in $dest_dir, such as a config file you don't want to overwrite. For example 'conf.json secrets.json logs' (no trailing `/` for folders)
- `--full_replace=`: Remove previous sources before installing new sources (can be 1 or 0, default to 0)
**Details**:
This helper will read infos from the 'sources' resources in the `manifest.toml` of the app
and expect a structure like:
```toml
[resources.sources]
[resources.sources.main]
url = "https://some.address.to/download/the/app/archive"
sha256 = "0123456789abcdef" # The sha256 sum of the asset obtained from the URL
```
(See also the resources documentation which may be more complete?)
##### Optional flags in the 'sources' resource
```text
format = "tar.gz"/xz/bz2/tar # automatically guessed from the extension of the URL, but can be set explicitly. Will use `tar` to extract
"zip" # automatically guessed from the extension of the URL, but can be set explicitly. Will use `unzip` to extract
"docker" # useful to extract files from an already-built docker image (instead of rebuilding them locally). Will use `docker-image-extract` to extract
"whatever" # an arbitrary value, not really meaningful except to imply that the file won't be extracted
in_subdir = true # default, there's an intermediate subdir in the archive before accessing the actual files
false # sources are directly in the archive root
n # (special cases) an integer representing a number of subdirs levels to get rid of
extract = true # default if file is indeed an archive such as .zip, .tar.gz, .tar.bz2, ...
= false # default if file 'format' is not set and the file is not to be extracted because it is not an archive but a script or binary or whatever asset.
# in which case the file will only be `mv`ed to the location possibly renamed using the `rename` value
rename = "whatever_your_want" # to be used for convenience when `extract` is false and the default name of the file is not practical (the default filename being the value of `source_id` arg and not the upstream basename).
platform = "linux/amd64" # (defaults to "linux/$YNH_ARCH") to be used in conjonction with `format = "docker"` to specify which architecture to extract for
```
You may also define assets url and checksum per-architectures such as:
```toml
[resources.sources]
[resources.sources.main]
amd64.url = "https://some.address.to/download/the/app/archive/when/amd64"
amd64.sha256 = "0123456789abcdef"
armhf.url = "https://some.address.to/download/the/app/archive/when/armhf"
armhf.sha256 = "fedcba9876543210"
```
In which case `ynh_setup_source --dest_dir="$install_dir"` will automatically pick the appropriate source depending on the arch
The helper will:
- Download the specific URL if there is no local archive
- Check the integrity with the specific sha256 sum
- Uncompress the archive to `$dest_dir`.
- If `in_subdir` is true, the first level directory of the archive will be removed.
- If `in_subdir` is a numeric value, the N first level directories will be removed.
- Patches named `patches/${src_id}/*.patch` will be applied to `$dest_dir`
- Apply sane default permissions (see _ynh_apply_default_permissions)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/sources#L83)
This is coupled to the 'database' resource in the manifest.toml - at least for mysql/postgresql. Mongodb/redis may have better integration in the future.
### Mysql`ynh_mysql_db_shell`
Run SQL instructions in a database ($db_name by default)
**Usage**: `ynh_mysql_db_shell [database] <<< "instructions"`
**Arguments**:
- `database=`: the database to connect to (by default, $db_name)
**Examples**:
- `ynh_mysql_db_shell $db_name <<< "UPDATE ...;"`
- `ynh_mysql_db_shell < /path/to/file.sql`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mysql#L30)
`ynh_mysql_dump_db`
Dump a database
**Usage**: `ynh_mysql_dump_db database`
**Arguments**:
- `database`: the database name to dump (by default, $db_name)
**Returns**: The mysqldump output
**Example**: `ynh_mysql_dump_db "roundcube" > ./dump.sql`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mysql#L92)
`ynh_psql_db_shell`
Run SQL instructions in a database ($db_name by default)
**Usage**: `ynh_psql_db_shell database <<< "instructions"`
**Arguments**:
- `database`: the database to connect to (by default, $db_name)
**Examples**:
- `ynh_psql_db_shell $db_name <<< "UPDATE ...;"`
- `ynh_psql_db_shell < /path/to/file.sql`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/postgresql#L34)
`ynh_psql_dump_db`
Dump a database
**Usage**: `ynh_psql_dump_db database`
**Arguments**:
- `database`: the database name to dump (by default, $db_name)
**Returns**: the psqldump output
**Example**: `ynh_psql_dump_db 'roundcube' > ./dump.sql`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/postgresql#L89)
`ynh_mongo_exec`
Execute a mongo command
**Usage**: `ynh_mongo_exec [--database=database] --command="command"`
**Arguments**:
- `--database=`: The database to connect to
- `--command=`: The command to evaluate
**Example**: `ynh_mongo_exec --command='db.getMongo().getDBNames().indexOf("wekan")' example: ynh_mongo_exec --command="db.getMongo().getDBNames().indexOf(\"wekan\")"`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L31)
`ynh_mongo_dump_db`
Dump a database
**Usage**: `ynh_mongo_dump_db --database=database`
**Arguments**:
- `--database=`: The database name to dump
**Returns**: the mongodump output
**Example**: `ynh_mongo_dump_db --database=wekan > ./dump.bson`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L81)
`ynh_mongo_database_exists`
Check if a mongo database exists
**Usage**: `ynh_mongo_database_exists --database=database
| exit: Return 1 if the database doesn't exist, 0 otherwise`
**Arguments**:
- `--database=`: The database for which to check existence
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L124)
`ynh_mongo_restore_db`
Restore a database
**Usage**: `ynh_mongo_restore_db --database=database`
**Arguments**:
- `--database=`: The database name to restore
**Example**: `ynh_mongo_restore_db --database=wekan < ./dump.bson`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L146)
`ynh_mongo_setup_db`
Create a database, a user and its password. Then store the password in the app's config
**Usage**: `ynh_mongo_setup_db --db_user=user --db_name=name [--db_pwd=pwd]`
**Arguments**:
- `--db_user=`: Owner of the database
- `--db_name=`: Name of the database
- `--db_pwd=`: Password of the database. If not provided, a password will be generated
**Details**:
After executing this helper, the password of the created database will be available in $db_pwd
It will also be stored as "mongopwd" into the app settings.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L187)
`ynh_mongo_remove_db`
Remove a database if it exists, and the associated user
**Usage**: `ynh_mongo_remove_db --db_user=user --db_name=name`
**Arguments**:
- `--db_user=`: Owner of the database
- `--db_name=`: Name of the database
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L214)
`ynh_install_mongo`
Install MongoDB and integrate MongoDB service in YunoHost
**Usage**: `ynh_install_mongo`
**Details**:
The installed version is defined by $mongo_version which should be defined as global prior to calling this helper
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L238)
`ynh_remove_mongo`
Remove MongoDB
Only remove the MongoDB service integration in YunoHost for now
if MongoDB package as been removed
**Usage**: `ynh_remove_mongo`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/mongodb#L279)
`ynh_redis_get_free_db`
get the first available redis database
**Usage**: `ynh_redis_get_free_db`
**Returns**: the database number to use
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/redis#L25)
`ynh_redis_remove_db`
Erase a redis database so it can be reused by other apps.
**Usage**: `ynh_redis_remove_db database`
**Arguments**:
- `database`: the database to erase
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/redis#L51)
`ynh_config_add`
Create a dedicated config file from a template
**Usage**: `ynh_config_add --template="template" --destination="destination"`
**Arguments**:
- `--template=`: Template config file to use
- `--destination=`: Destination of the config file
- `--jinja`: Use jinja template instead of the simple `__MY_VAR__` templating format
**Examples**:
- `ynh_config_add --template=".env" --destination="$install_dir/.env" # (use the template file "conf/.env" from the app's package)`
- `ynh_config_add --jinja --template="config.j2" --destination="$install_dir/config" # (use the template file "conf/config.j2" from the app's package)`
**Details**:
The template can be 1) the name of a file in the `conf` directory of
the app, 2) a relative path or 3) an absolute path.
This applies a simple templating format which covers a good 95% of cases,
where patterns like `__FOO__` are replaced by the bash variable `$foo`, for example:
`__DOMAIN__` by `$domain`
`__PATH__` by `$path`
`__APP__` by `$app`
`__VAR_1__` by `$var_1`
`__VAR_2__` by `$var_2`
For this to work, template tags must be in uppercase and variables names must be in lowercase (for instance `__MY_var__` or `$myVar` would not be replaced as expected).
Special case for `__PATH__/` which is replaced by `/` instead of `//` if `$path` is `/`
##### When --jinja is enabled
This option is meant for advanced use-cases where the "simple" templating
mode ain't enough because you need conditional blocks or loops.
For a full documentation of jinja's syntax you can refer to [the official Jinja documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/).
Note that in YunoHost context, all variables are from shell variables and therefore are strings
To help handling complex data Jinja engine are executed with theses additional filters:
- from_json: load a string as Json and return an object
- from_yaml: load a string as Yaml and return an object
- from_toml: load a string as Toml and return an object
- to_json: serialize to string an object to Json
- to_yaml: serialize to string an object to Yaml
- to_toml: serialize to string an object to Toml
So by example, if you want to convert a json string `$my_json` to Toml, you can to this way:
`{{ my_json | from_json | to_toml }}`
Or you can iterate on a Json list `my_list='["a", "b", "c"]'` this way:
```
{% for i in my_list | from_json %}
value {{ i }}
{% endfor }}
```
which will result:
```
value a
value b
value c
```
##### Keeping track of manual changes by the admin
The helper will verify the checksum and backup the destination file
if it's different before applying the new template.
And it will calculate and store the destination file checksum
into the app settings when configuration is done.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/templating#L86)
`ynh_read_var_in_file`
Get a value from heterogeneous file (yaml, json, php, python...)
**Usage**: `ynh_read_var_in_file --file=PATH --key=KEY`
**Arguments**:
- `--file=`: the path to the file
- `--key=`: the key to get
- `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file)
**Details**:
This helpers match several var affectation use case in several languages
We don't use jq or equivalent to keep comments and blank space in files
This helpers work line by line, it is not able to work correctly
if you have several identical keys in your files
Example of line this helpers can managed correctly
```text
.yml
title: YunoHost documentation
email: 'yunohost@yunohost.org'
.json
"theme": "colib'ris",
"port": 8102
"some_boolean": false,
"user": null
.ini
some_boolean = On
action = "Clear"
port = 20
.php
$user=
user => 20
.py
USER = 8102
user = 'https://donate.local'
CUSTOM['user'] = 'YunoHost'
```
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/templating#L224)
`ynh_write_var_in_file`
Set a value into heterogeneous file (yaml, json, php, python...)
**Usage**: `ynh_write_var_in_file --file=PATH --key=KEY --value=VALUE`
**Arguments**:
- `--file=`: the path to the file
- `--key=`: the key to set
- `--value=`: the value to set
- `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file)
**Details**:
This helpers replaces several var affectation use case in several languages
We don't use jq or equivalent to keep comments and blank space in files
This helpers works line by line, and is not made to replace a type by another.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/templating#L304)
`ynh_config_add_nginx`
Create a dedicated nginx config
**Usage**: `ynh_config_add_nginx`
**Details**:
This will use a template in `../conf/nginx.conf`
See the documentation of `ynh_config_add` for a description of the template
format and how placeholders are replaced with actual variables.
Additionally, ynh_config_add_nginx will replace:
- `#sub_path_only` by empty string if `path` is not `'/'`
- `#root_path_only` by empty string if `path` *is* `'/'`
This allows to enable/disable specific behaviors dependenging on the install
location
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/nginx#L36)
`ynh_config_remove_nginx`
Remove the dedicated nginx config
**Usage**: `ynh_config_remove_nginx`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/nginx#L61)
`ynh_config_change_url_nginx`
Regen the nginx config in a change url context
**Usage**: `ynh_config_change_url_nginx`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/nginx#L69)
`ynh_config_add_phpfpm`
Create a dedicated PHP-FPM config
**Usage**: `ynh_config_add_phpfpm`
**Details**:
This will automatically generate an appropriate PHP-FPM configuration for this app.
The resulting configuration will be deployed to the appropriate place:
`/etc/php/$php_version/fpm/pool.d/$app.conf`
If the app provides a `conf/extra_php-fpm.conf` template, it will be appended
to the generated configuration. (In the vast majority of cases, this shouldnt
be necessary)
$php_version should be defined prior to calling this helper, but there should
be no reason to manually set it, as it is automatically set by the apt
helpers/resources when installing phpX.Y dependencies (PHP apps should at
least install phpX.Y-fpm using the `apt` helper/resource)
`$php_group` can be defined as a global (from `_common.sh`) if the worker
processes should run with a different group than `$app`
Additional "pm" and "php_admin_value" settings which are meant to be possibly
configurable by admins from a future standard config panel at some point,
related to performance and availability of the app, for which tweaking may be
required if the app is used by "plenty" of users and other memory/CPU load
considerations....
If you have good reasons to be willing to use different
defaults than the one set by this helper (while still allowing admin to
override it) you should use `ynh_app_setting_set_default`
- `$php_upload_max_filezise`: corresponds upload_max_filesize and post_max_size. Defaults to 50M
- `$php_process_management`: corresponds to "pm" (ondemand, dynamic, static). Defaults to ondemand
- `$php_max_children`: by default, computed from "total RAM" divided by 40, cf `_default_php_max_children`
- `$php_memory_limit`: by default, 128M (from global php.ini)
Note that if $php_process_management is set to "dynamic", then these
variables MUST be defined prior to calling the helper (no default value) ...
Check PHP-FPM's manual for more info on what these are (: ...
- `$php_start_servers`
- `$php_min_spare_servers`
- `$php_max_spare_servers`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/php#L68)
`ynh_config_remove_phpfpm`
Remove the dedicated PHP-FPM config
**Usage**: `ynh_config_remove_phpfpm`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/php#L144)
`ynh_config_add_systemd`
Create a dedicated systemd config
**Usage**: `ynh_config_add_systemd [--mount=mount] [--service=service] [--template=template]`
**Arguments**:
- `--mount=`: Mount name (optionnal)
- `--service=`: Service name (optionnal, `$app` by default)
- `--template=`: Name of template file (optionnal, this is 'systemd.service' by default, meaning `../conf/systemd.service` will be used as template)
**Details**:
This will use the template `../conf/`ynh_config_remove_systemd`
Remove the dedicated systemd config
**Usage**: `ynh_config_remove_systemd service`
**Arguments**:
- `service`: Service name (optionnal, $app by default)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/systemd#L58)
`ynh_systemctl`
Start (or other actions) a service, print a log in case of failure and optionnaly wait until the service is completely started
**Usage**: `ynh_systemctl [--service=service] [--action=action] [ [--wait_until="line to match"] [--log_path=log_path] [--timeout=300] [--length=20] ]`
**Arguments**:
- `--service=`: Name of the service to start. Default : `$app`
- `--action=`: Action to perform with systemctl. Default: start
- `--wait_until=`: The pattern to find in the log to attest the service is effectively fully started.
- `--log_path=`: Log file - Path to the log file. Default : `/var/log/$app/$app.log`; `systemd` to listen on `journalctl --unit=$service`
- `--timeout=`: Timeout - The maximum time to wait before ending the watching. Default : 60 seconds.
- `--length=`: Length of the error log displayed for debugging : Default : 20
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/systemd#L83)
`ynh_config_add_fail2ban`
Create a dedicated fail2ban config (jail and filter conf files)
**Usage**: `ynh_config_add_fail2ban --logpath=log_file --failregex=filter`
**Arguments**:
- `--logpath=`: Log file to be checked by fail2ban
- `--failregex=`: Failregex to be looked for by fail2ban
**Details**:
If --logpath / --failregex are provided, the helper will generate the appropriate conf using these.
Otherwise, it will assume that the app provided templates, namely
`../conf/f2b_jail.conf` and `../conf/f2b_filter.conf`
They will typically look like (for example here for synapse):
```toml
f2b_jail.conf:
[__APP__]
enabled = true
port = http,https
filter = __APP__
logpath = /var/log/__APP__/logfile.log
maxretry = 5
```
```toml
f2b_filter.conf:
[INCLUDES]
before = common.conf
[Definition]
# Part of regex definition (just used to make more easy to make the global regex)
__synapse_start_line = .? \- synapse\..+ \-
# Regex definition.
failregex = ^%(__synapse_start_line)s INFO \- POST\-(\d+)\- `ynh_config_remove_fail2ban`
Remove the dedicated fail2ban config (jail and filter conf files)
**Usage**: `ynh_config_remove_fail2ban`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/fail2ban#L134)
`ynh_config_add_logrotate`
Add a logrotate configuration to manage log files / log directory
**Usage**: `ynh_config_add_logrotate [/path/to/log/file/or/folder]`
**Details**:
If not argument is provided, `/var/log/$app/*.log` is used as default.
The configuration is autogenerated by YunoHost
(ie it doesnt come from a specific app template like nginx or systemd conf)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logrotate#L31)
`ynh_config_remove_logrotate`
Remove the app's logrotate config.
**Usage**: ``
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logrotate#L87)
`ynh_exec_as_app`
Execute a command after sudoing as $app
**Usage**: `ynh_exec_as_app COMMAND [ARG ...]`
**Details**:
Note that the $PATH variable is preserved (using env PATH=$PATH)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L76)
`ynh_local_curl`
Curl abstraction to help with POST requests to local pages (such as installation forms)
**Usage**: `ynh_local_curl "page_uri" "key1=value1" "key2=value2" ...`
**Arguments**:
- `page_uri`: Path (relative to `$path`) of the page where POST data will be sent
- `key1=value1`: (Optionnal) POST key and corresponding value
- `key2=value2`: (Optionnal) Another POST key and corresponding value
- `...`: (Optionnal) More POST keys and values
**Example**: `ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2"`
**Details**:
For multiple calls, cookies are persisted between each call for the same app
`$domain` and `$path` should be defined externally (and correspond to the domain.tld and the /path (of the app?))
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L97)
`ynh_safe_rm`
Remove a file or a directory, checking beforehand that it's not a disastrous location to rm such as entire /var or /home
**Usage**: `ynh_safe_rm path_to_remove`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L177)
`ynh_read_manifest`
Read the value of a key in the app's manifest
**Usage**: `ynh_read_manifest "key"`
**Arguments**:
- `key`: Name of the key to find
**Returns**: the value associate to that key
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L203)
`ynh_app_upstream_version`
Return the app upstream version, deduced from `$YNH_APP_MANIFEST_VERSION` and strippig the `~ynhX` part
**Usage**: `ynh_app_upstream_version`
**Returns**: the version number of the upstream app
**Details**:
For example, if the manifest contains `4.3-2~ynh3` the function will return `4.3-2`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L213)
`ynh_app_upstream_version_changed`
Return 0 if the "upstream" part of the version changed, or 1 otherwise (ie only the ~ynh suffix changed)
**Usage**: `if ynh_app_upstream_version_changed; then ...`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L220)
`ynh_app_upgrading_from_version_before`
Compare the current package version is strictly lower than another version given as an argument
**Usage**: ``
**Example**: `if ynh_app_upgrading_from_version_before 2.3.2~ynh1; then ...`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L228)
`ynh_app_upgrading_from_version_before_or_equal_to`
Compare the current package version is lower or equal to another version given as an argument
**Usage**: ``
**Example**: `if ynh_app_upgrading_from_version_before_or_equal_to 2.3.2~ynh1; then ...`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L238)
`ynh_validate_ip`
Validate an IP address
**Usage**: `ynh_validate_ip --family=family --ip_address=ip_address`
**Returns**: 0 for valid ip addresses, 1 otherwise
**Example**: `ynh_validate_ip 4 111.222.333.444`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L318)
`ynh_in_ci_tests`
Check if the scripts are being run by the package_check in CI
**Usage**: `ynh_in_ci_tests`
**Details**:
Return 0 if in CI, 1 otherwise
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L382)
`ynh_user_get_info`
Retrieve a YunoHost user information
**Usage**: `ynh_user_get_info --username=username --key=key`
**Arguments**:
- `--username=`: the username to retrieve info from
- `--key=`: the key to retrieve
**Returns**: the value associate to that key
**Example**: `mail=$(ynh_user_get_info --username="toto" --key=mail)`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L394)
`ynh_user_list`
Get the list of YunoHost users
**Usage**: `ynh_user_list`
**Returns**: one username per line as strings
**Example**: `for u in $(ynh_user_list); do ... ; done`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L411)
`ynh_spawn_app_shell`
Spawn a Bash shell with the app environment loaded
**Usage**: `ynh_spawn_app_shell`
**Examples**:
- `ynh_spawn_app_shell <<< 'echo "$USER"'`
- `ynh_spawn_app_shell < /tmp/some_script.bash`
**Details**:
The spawned shell will have environment variables loaded and environment files sourced
from the app's service configuration file (defaults to $app.service, overridable by the packager with `service` setting).
If the app relies on a specific PHP version, then `php` will be aliased that version. The PHP command will also be appended with the `phpflags` settings.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L426)
`ynh_add_swap`
Add swap
**Usage**: `ynh_add_swap --size=SWAP in Mb`
**Arguments**:
- `-s`, `--size=`: Amount of SWAP to add in Mb.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L494)
`ynh_smart_mktemp`
Check available space before creating a temp directory.
**Usage**: `ynh_smart_mktemp --min_size="Min size"`
**Arguments**:
- `-s`, `--min_size=`: Minimal size needed for the temporary directory, in Mb
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/0-utils#L594)
`ynh_app_setting_get`
Get an application setting
**Usage**: `ynh_app_setting_get --key=key`
**Arguments**:
- `--app=`: the application id (global $app by default)
- `--key=`: the setting to get
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/setting#L26)
`ynh_app_setting_set`
Set an application setting
**Usage**: `ynh_app_setting_set --key=key --value=value`
**Arguments**:
- `--app=`: the application id (global $app by default)
- `--key=`: the setting name to set
- `--value=`: the setting value to set
**Details**:
When choosing the setting key's name, note that including the following keywords will make the associated setting's value appear masked in the debug logs (cf. [related code](https://github.com/YunoHost/yunohost/blob/216210d5e97070b85c96ebb4548c6abf36987771/src/log.py#L571)): `pwd`, `pass`, `passwd`, `password`, `passphrase`, `secret\w*` (regex), `\w+key` (regex), `token`, `PASSPHRASE`
This is meant to allow sharing the logs while preserving confidential data, but having this in mind is useful would you expect to see those values while debugging your scripts.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/setting#L48)
`ynh_app_setting_set_default`
Set an application setting but only if the "$key" variable ain't set yet
**Usage**: `ynh_app_setting_set_default --key=key --value=value`
**Arguments**:
- `--app=`: the application id (global $app by default)
- `--key=`: the setting name to set
- `--value=`: the default setting value to set
**Details**:
Note that it doesn't just define the setting but ALSO define the $foobar variable
Hence it's meant as a replacement for this legacy overly complex syntax:
```bash
if [ -z "${foo:-}" ]
then
foo="bar"
ynh_app_setting_set --key="foo" --value="$foo"
fi
```
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/setting#L80)
`ynh_app_setting_delete`
Delete an application setting
**Usage**: `ynh_app_setting_delete --key=key`
**Arguments**:
- `--app=`: the application id (global $app by default)
- `--key=`: the setting to delete
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/setting#L102)
`ynh_string_random`
Generate a random string
**Usage**: `ynh_string_random [--length=string_length]`
**Arguments**:
- `--length=`: the string length to generate (default: 24)
- `--filter=`: the kind of characters accepted in the output (default: 'A-Za-z0-9')
**Returns**: the generated string
**Example**: `pwd=$(ynh_string_random --length=8)`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/string#L29)
`ynh_replace`
Substitute/replace a string (or expression) by another in a file
**Usage**: `ynh_replace --match=match --replace=replace --file=file`
**Arguments**:
- `--match=`: String to be searched and replaced in the file
- `--replace=`: String that will replace matches
- `--file=`: File in which the string will be replaced.
**Details**:
As this helper is based on sed command, regular expressions and references to
sub-expressions can be used (see sed manual page for more information). In particular
for back-references, as in sed without specific options, you will need to escape
the parentheses of the capture group.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/string#L53)
`ynh_replace_regex`
Substitute/replace a regex in a file
**Usage**: `ynh_replace_regex --match=match --replace=replace --file=file`
**Arguments**:
- `--match=`: String to be searched and replaced in the file
- `--replace=`: String that will replace matches
- `--file=`: File in which the string will be replaced.
**Details**:
This helper will use ynh_replace, but as you can use special
characters, you can't use some regular expressions and sub-expressions.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/string#L81)
`ynh_normalize_url_path`
Normalize the url path syntax
**Usage**: `ynh_normalize_url_path path_to_normalize`
**Examples**:
- `url_path=$(ynh_normalize_url_path $url_path)`
- `ynh_normalize_url_path example # -> /example`
- `ynh_normalize_url_path /example # -> /example`
- `ynh_normalize_url_path /example/ # -> /example`
- `ynh_normalize_url_path / # -> /`
**Details**:
Handle the slash at the beginning of path and its absence at ending
Return a normalized url path
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/string#L136)
`ynh_backup`
Add a file or a directory to the list of paths to backup
**Usage**: `ynh_backup /path/to/stuff`
**Details**:
NB : note that this helper does *NOT* perform any copy in itself, it only
declares stuff to be backuped via a CSV which is later picked up by the core
NB 2 : there is a specific behavior for $data_dir (or childs of $data_dir) and
/var/log/$app which are *NOT* backedup during safety-backup-before-upgrade,
OR if the setting "do_not_backup_data" is equals 1 for that app
The rationale is that these directories are usually too heavy to be integrated in every backup
(think for example about Nextcloud with quite a lot of data, or an app with a lot of media files...)
This is coupled to the fact that $data_dir and the log dir won't be (and
should NOT) be deleted during remove, unless --purge is used. Hence, if the
upgrade fails and the script is removed prior to restoring the backup, the
data/logs are not destroyed.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/backup#L42)
`ynh_restore`
Restore a file or a directory from the backup archive
**Usage**: `ynh_restore /path/to/stuff`
**Examples**:
- `ynh_restore "/etc/nginx/conf.d/$domain.d/$app.conf"`
**Details**:
If the file or dir to be restored already exists on the system and is lighter
than 500 Mo, it is backed up in `/var/cache/yunohost/appconfbackup/`.
Otherwise, the existing file or dir is removed.
if `apps/$app/etc/nginx/conf.d/$domain.d/$app.conf` exists, restore it into
`/etc/nginx/conf.d/$domain.d/$app.conf`
otheriwse, search for a match in the csv (eg: conf/nginx.conf) and restore it into
`/etc/nginx/conf.d/$domain.d/$app.conf`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/backup#L147)
`ynh_restore_everything`
Restore all files that were previously backuped in an app backup script
**Usage**: `ynh_restore_everything`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/backup#L204)
`ynh_store_file_checksum`
Calculate and store a file checksum into the app settings
**Usage**: `ynh_store_file_checksum /path/to/file`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/backup#L226)
`ynh_backup_if_checksum_is_different`
Verify the checksum and backup the file if it's different
**Usage**: `ynh_backup_if_checksum_is_different /path/to/file`
**Details**:
This helper is primarily meant to allow to easily backup personalised/manually
modified config files.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/backup#L257)
`ynh_delete_file_checksum`
Delete a file checksum from the app settings
**Usage**: `ynh_delete_file_checksum /path/to/file`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/backup#L287)
`ynh_die`
Print a message to stderr and terminate the current script
**Usage**: `ynh_die "Some message"`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logging#L24)
`ynh_print_info`
Print an "INFO" message
**Usage**: `ynh_print_info "Some message"`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logging#L38)
`ynh_print_warn`
Print a warning on stderr
**Usage**: `ynh_print_warn "Some message"`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logging#L45)
`ynh_hide_warnings`
Execute a command and redirect stderr to stdout
**Usage**: `ynh_hide_warnings your command and args`
**Arguments**:
- `command`: command to execute
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logging#L54)
`ynh_exec_and_print_stderr_only_if_error`
Execute a command and redirect stderr in /dev/null. Print stderr on error.
**Usage**: `ynh_exec_and_print_stderr_only_if_error your command and args`
**Arguments**:
- `command`: command to execute
**Details**:
Note that you should NOT quote the command but only prefix it with ynh_exec_and_print_stderr_only_if_error
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logging#L65)
`ynh_return`
Return data to the YunoHost core for later processing (to be used by special hooks like app config panel and core diagnosis)
**Usage**: `ynh_return somedata`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logging#L80)
`ynh_script_progression`
Print a progress bar showing the progression of an app script
**Usage**: `ynh_script_progression "Some message"`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/logging#L98)
`ynh_multimedia_build_main_dir`
Initialize the multimedia directory system
**Usage**: `ynh_multimedia_build_main_dir`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/multimedia#L27)
`ynh_multimedia_addfolder`
Add a directory in `yunohost.multimedia`
**Usage**: `ynh_multimedia_addfolder --source_dir="source_dir" --dest_dir="dest_dir"`
**Arguments**:
- `--source_dir=`: Source directory - The real directory which contains your medias.
- `--dest_dir=`: Destination directory - The name and the place of the symbolic link, relative to `/home/yunohost.multimedia`
**Details**:
This "directory" will be a symbolic link to a existing directory.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/multimedia#L86)
`ynh_multimedia_addaccess`
Add an user to the multimedia group, in turn having write permission in multimedia directories
**Usage**: `ynh_multimedia_addaccess user_name`
**Arguments**:
- `user_name`: The name of the user which gain this access.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/multimedia#L112)
`ynh_permission_delete`
Remove a permission for the app (note that when the app is removed all permission is automatically removed)
**Usage**: `ynh_permission_delete --permission="permission"`
**Arguments**:
- `--permission=`: the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
**Example**: `ynh_permission_delete --permission=editors`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/permission#L158)
`ynh_permission_exists`
Check if a permission exists
**Usage**: `ynh_permission_exists --permission=permission
| exit: Return 1 if the permission doesn't exist, 0 otherwise`
**Arguments**:
- `--permission=`: the permission to check
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/permission#L173)
`ynh_permission_url`
Redefine the url associated to a permission
**Usage**: `ynh_permission_url --permission "permission" [--url="url"] [--add_url="new-url" [ "other-new-url" ]] [--remove_url="old-url" [ "other-old-url" ]]
[--auth_header=true|false] [--clear_urls]`
**Arguments**:
- `--permission=`: the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
- `--url=`: (optional) URL for which access will be allowed/forbidden. Note that if you want to remove url you can pass an empty sting as arguments ("").
- `--add_url=`: (optional) List of additional url to add for which access will be allowed/forbidden.
- `--remove_url=`: (optional) List of additional url to remove for which access will be allowed/forbidden
- `--auth_header=`: (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application
- `--clear_urls`: (optional) Clean all urls (url and additional_urls)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/permission#L194)
`ynh_permission_update`
Update a permission for the app
**Usage**: `ynh_permission_update --permission "permission" [--add="group" ["group" ...]] [--remove="group" ["group" ...]]`
**Arguments**:
- `--permission=`: the name for the permission (by default a permission named "main" already exist)
- `--add=`: the list of group or users to enable add to the permission
- `--remove=`: the list of group or users to remove from the permission
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/permission#L257)
`ynh_permission_has_user`
Check if a permission has an user
**Usage**: `ynh_permission_has_user --permission=permission --user=user
| exit: Return 1 if the permission doesn't have that user or doesn't exist, 0 otherwise`
**Arguments**:
- `--permission=`: the permission to check
- `--user=`: the user seek in the permission
**Example**: `ynh_permission_has_user --permission=main --user=visitors`
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/permission#L298)
`ynh_apt_install_dependencies`
Define and install dependencies with a equivs control file
**Usage**: `ynh_apt_install_dependencies dep [dep [...]]`
**Arguments**:
- `dep`: the package name to install in dependence.
- `"dep1|dep2|…"`: You can specify alternatives. It will require to install (dep1 or dep2, etc).
**Details**:
example : ynh_apt_install_dependencies dep1 dep2 "dep3|dep4|dep5"
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/apt#L31)
`ynh_apt_remove_dependencies`
Remove fake package and its dependencies
**Usage**: `ynh_apt_remove_dependencies`
**Details**:
Dependencies will removed only if no other package need them.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/apt#L177)
`ynh_apt_install_dependencies_from_extra_repository`
Install packages from an extra repository properly.
**Usage**: `ynh_apt_install_dependencies_from_extra_repository --repo="repo" --package="dep1 dep2" --key=key_url`
**Arguments**:
- `--repo=`: Complete url of the extra repository.
- `--package=`: The packages to install from this extra repository
- `--key=`: url to get the public key.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/apt#L207)
`ynh_system_user_exists`
Check if a user exists on the system
**Usage**: `ynh_system_user_exists --username=username`
**Arguments**:
- `--username=`: the username to check
**Returns**: 0 if the user exists, 1 otherwise.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/systemuser#L26)
`ynh_system_group_exists`
Check if a group exists on the system
**Usage**: `ynh_system_group_exists --group=group`
**Arguments**:
- `--group=`: the group to check
**Returns**: 0 if the group exists, 1 otherwise.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/systemuser#L41)
`ynh_system_user_create`
Create a system user
**Usage**: `ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] [--groups="group1 group2"]`
**Arguments**:
- `--username=`: Name of the system user that will be create
- `--home_dir=`: Path of the home dir for the user. Usually the final path of the app. If this argument is omitted, the user will be created without home
- `--use_shell`: Create a user using the default login shell if present. If this argument is omitted, the user will be created with /usr/sbin/nologin shell
- `--groups`: Add the user to system groups. Typically meant to add the user to the ssh.app / sftp.app group (e.g. for borgserver, my_webapp)
**Details**:
Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability) :
```bash
ynh_system_user_create --username=nextcloud
```
Create a discourse user using /var/www/discourse as home directory and the default login shell :
```bash
ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell
```
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/systemuser#L70)
`ynh_system_user_delete`
Delete a system user
**Usage**: `ynh_system_user_delete --username=user_name`
**Arguments**:
- `--username=`: Name of the system user that will be create
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/systemuser#L108)
`ynh_nodejs_install`
Install a specific version of nodejs, using 'n'
**Usage**: `ynh_nodejs_install`
**Details**:
The installed version is defined by `$nodejs_version` which should be defined as global prior to calling this helper
`n` (Node version management) uses the `PATH` variable to store the path of the version of node it is going to use.
That's how it changes the version
The helper adds the appropriate, specific version of nodejs to the `$PATH` variable (which
is preserved when calling ynh_exec_as_app). Also defines:
- `$path_with_nodejs` to be used in the systemd config (`Environment="PATH=__PATH_WITH_NODEJS__"`)
- `$nodejs_dir`, the directory containing the specific version of nodejs, which may be used in the systemd config too (e.g. `ExecStart=__NODEJS_DIR__/node foo bar`)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/nodejs#L73)
`ynh_nodejs_remove`
Remove the version of node used by the app.
**Usage**: `ynh_nodejs_remove`
**Details**:
This helper will check if another app uses the same version of node.
- If not, this version of node will be removed.
- If no other app uses node, n will be also removed.
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/nodejs#L107)
`ynh_ruby_install`
Install a specific version of Ruby using rbenv
**Usage**: `ynh_ruby_install`
**Details**:
The installed version is defined by `$ruby_version` which should be defined as global prior to calling this helper
The helper adds the appropriate, specific version of ruby to the `$PATH` variable (which
is preserved when calling ynh_exec_as_app). Also defines:
- `$path_with_ruby` to be used in the systemd config (`Environment="PATH=__PATH_WITH_RUBY__"`)
- `$ruby_dir`, the directory containing the specific version of ruby, which may be used in the systemd config too (e.g. `ExecStart=__RUBY_DIR__/ruby foo bar`)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/ruby#L68)
`ynh_ruby_remove`
Remove the version of Ruby used by the app.
**Usage**: `ynh_ruby_remove`
**Details**:
This helper will also cleanup unused Ruby versions
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/ruby#L110)
`ynh_go_install`
Install a specific version of Go using goenv
**Usage**: `ynh_go_install`
**Details**:
The installed version is defined by `$go_version` which should be defined as global prior to calling this helper
The helper adds the appropriate, specific version of go to the `$PATH` variable (which
is preserved when calling `ynh_exec_as_app`). Also defines:
- `$path_with_go` (the value of the modified `$PATH`, but you dont really need it?)
- `$go_dir` (the directory containing the specific go version)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/go#L68)
`ynh_go_remove`
Remove the version of Go used by the app.
**Usage**: `ynh_go_remove`
**Details**:
This helper will also cleanup Go versions
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/go#L99)
`ynh_composer_install`
Install and initialize Composer in the given directory
**Usage**: `ynh_composer_install`
**Details**:
The installed version is defined by `$composer_version` which should be defined
as global prior to calling this helper.
Will use `$install_dir` as workdir unless `$composer_workdir` exists (but that shouldnt be necessary)
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/composer#L29)
`ynh_composer_exec`
Execute a command with Composer
**Usage**: `ynh_composer_exec commands`
**Details**:
Will use `$install_dir` as workdir unless `$composer_workdir` exists (but that shouldnt be necessary)
You may also define `composer_user=root` prior to call this helper if you
absolutely need composer to run as root, but this is discouraged...
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/3572fc9dff10b9f4f4ab30efe88a9b145867c241/helpers/helpers.v2.1.d/composer#L55)
Basic example with raw stdout: get the timezone on the system
`config_panel.toml` ```toml [main.main.timezone] ask = "Timezone" type = "string" ``` `scripts/config` ```bash get__timezone() { echo "$(cat /etc/timezone)" } ```Basic example with raw stdout containing a yaml-sensitive character: return a HTML color code matched in a file
`config_panel.toml` ```toml [main.default_colors.background] ask = "Default background color" type = "color" default = "#cccccc" ``` `scripts/config` ```bash get__background() { current_color=$(grep 'id="backgroundColorPicker' "$install_dir/index.html" | grep -oP 'value="\K[^"]*') # e.g. #2B748B # explicitely add escaped quotes to protect YAML-sensitive comment char ('#') echo "\"$current_color\"" } ```Basic example with yaml-formated stdout : Display a list of available plugins
`config_panel.toml` ```toml [main.plugins.plugins] ask = "Plugin to activate" type = "tags" choices = [] ``` `scripts/config` ```bash get__plugins() { echo "choices: [$(ls $install_dir/plugins/ | tr '\n' ',')]" } ```Advanced example with yaml-formated stdout : Display the status of a VPN
`config_panel.toml` ```toml [main.cube.status] ask = "Custom getter alert" type = "alert" style = "info" bind = "null" # no behaviour on ``` `scripts/config` ```bash get__status() { if [ -f "/sys/class/net/tun0/operstate" ] && [ "$(cat /sys/class/net/tun0/operstate)" == "up" ] then cat << EOF style: success ask: en: Your VPN is running :) EOF else cat << EOF style: danger ask: en: Your VPN is down EOF fi } ```Basic example : Set the system timezone
`config_panel.toml` ```toml [main.main.timezone] ask = "Timezone" type = "string" ``` `scripts/config` ```bash set__timezone() { echo "$timezone" > /etc/timezone ynh_print_info "The timezone has been changed to $timezone" } ```Triggered after user creation
This hook is run at the end of the command `yunohost user create` or equivalent action in webadmin. ##### Environment variables - YNH_USER_USERNAME: The username of the created user - YNH_USER_MAIL: The mail of the created user - YNH_USER_PASSWORD: The **clear** password of the created user - YNH_USER_FIRSTNAME: The firstname of the created user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) - YNH_USER_LASTNAME: The lastname of the created user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) ##### Positionnal arguments (deprecated) - $1: The username of the created user - $2: The mail of the created user ##### No waited return ##### Examples ###### Send automatically a mail to new user ```bash #!/bin/bash domain=$(cat /etc/hostname) message="Hello $YNH_USER_FIRSTNAME, Welcome on $domain ! Feel free to change your password. Let me know if you have a problem, The admin of $domain " echo $message | mail -s "Welcome on $domain !" $YNH_USER_MAIL ```Triggered at the end of user deletion
This hook is run at the end of the command `yunohost user delete` or equivalent action in webadmin. ##### No environment variables ##### Positionnal arguments - $1: The username of the user deleted - $2: True if --purge option is used ##### No waited return ##### Examples ###### ```bash #!/bin/bash ```Triggered at the end of the user update
This hook is run at the end of the command `yunohost user update` or equivalent action in webadmin. #### Environment variables :::warning Only arguments given to the cli/api are given as environment variable. ::: - YNH_USER_USERNAME: The username of the updated user - YNH_USER_FIRSTNAME: The firstname of the updated user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) - YNH_USER_LASTNAME: The lastname of the updated user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) - YNH_USER_PASSWORD: The new password of the updated user - YNH_USER_MAILS: The mail and mail aliases of the updated user seperated by comma - YNH_USER_MAILFORWARDS: The list of forward mails of the updated user separated by comma - YNH_USER_MAILQUOTA: The quota of the updated user (could be 0 or a number following by one of this unit: b, k, M, G or T) #### No positionnal arguments #### No waited return #### Examples ##### Send a mail on password changing ```bash #!/bin/bash " domain=$(cat /etc/hostname) message="Hello, Your password has been successfully changed on $domain. If you have not asked for changing your password, you probably should contact the admin of $domain. " echo $message | mail -s "Your password has been changed on $domain !" $YNH_USER_USERNAME ```Triggered after adding a permission to users or groups
This hook is run at the end of the command `yunohost user permission add` or equivalent action in webadmin. #### No environment variables #### Positionnal arguments (deprecated) - $1: The app name - $2: The list of users added separated by comma - $3: The name of the sub permission (`main`, `admin`, etc.) - $4: The list of groups added separated by comma #### No waited return #### ExamplesTriggered after removing a pemission to users or groups
This hook is run at the end of the command `yunohost user permission remove` or equivalent action in webadmin. #### No environment variables #### Positionnal arguments (deprecated) - $1: The app name - $2: The list of users removed from the permission separated by comma - $3: The name of the sub permission (`main`, `admin`, etc.) - $4: The list of groups removed from the permission separated by comma #### No waited return #### ExamplesTriggered at the end of the domain add operation
This hook is run at the end of the command `yunohost domain add` or equivalent action in webadmin. #### No environment variable #### Positionnal arguments (deprecated) - $1: The domain added #### No waited return #### Examples ##### ```bash ```Triggered after removing the domain
This hook is run at the end of the command `yunohost domain remove` or equivalent action in webadmin. #### No environment variable #### Positionnal arguments (deprecated) - $1: The domain removed #### No waited return #### ExamplesTriggered after Let's encrypt certificate update
This hook is run at the end of the command `yunohost domain cert update` or equivalent action in webadmin. #### No environment variable #### Positionnal arguments - $1: The domain for which we have updated the certificate #### No waited return #### Examples ##### Restart a service after cert renewal ```bash #!/bin/bash systemctl restart gemserv ```Customized your DNS rules for your domains
This hook is run at the end of the command `yunohost domain dns suggest` or equivalent action in webadmin. Thanks to This hook you can customize #### Environment variables - `base_domain`: the top-level part of the domain - `suffix`: the subdomain part of the domain #### Positionnal arguments - $1: The base domain for which we want to build a DNS suggestion #### Waited return The script should return a JSON array with dictionnary in this format: ```json [ { 'type': 'SRV', 'name': 'stuff.foo.bar', 'value': 'yoloswag', 'ttl': 3600 } ] ``` #### Examples ##### Validate Let's Encrypt DNS challenge with a YunoHost DynDNS domain ```bash #!/bin/bash if [[ "$1" == "XXXX.nohost.me" ]] ; then echo "[ { 'type': 'TXT', 'name': '_acme-challenge', 'value': 'LETSENCRYPT_VALUE', 'ttl': 3600 } ]" fi ```Triggered after an app has changed of URL
This hook is run at the end of the command `yunohost app change-url` or equivalent action in webadmin. #### Environment variables - YNH_APP_OLD_DOMAIN: The old domain of the app - YNH_APP_OLD_PATH: The old path of the app - YNH_APP_NEW_DOMAIN: The new domain of the app - YNH_APP_NEW_PATH: The new path of the app #### No positionnal arguments #### No waited return #### ExamplesTriggered on app upgrade
This hook is run at the end of the command `yunohost app upgrade` or equivalent action in webadmin. #### Environment variables - YNH_APP_ID: The app id (for example nextcloud) - YNH_APP_INSTANCE_NAME: The app instance name (for example nextcloud__2) - YNH_APP_INSTANCE_NUMBER: The app instance number (for example 2) - YNH_APP_MANIFEST_VERSION: The app manifest version (for example 1 or ?) - YNH_ARCH: The arch as returned by `dpkg --print-architecture` - YNH_APP_UPGRADE_TYPE: The type of upgrade (UPGRADE_PACKAGE, UPGRADE_APP, UPGRADE_FULL) - YNH_APP_MANIFEST_VERSION: The version number - YNH_APP_CURRENT_VERSION: The version number of the app (in the YunoHost format) - NO_BACKUP_UPGRADE: 1 if we don't want to backup else 0 #### No positionnal arguments #### No waited return #### Examples ##### Change a settings in an app config file (unmanaged by config panel) ```bash #!/bin/bash source /usr/share/yunohost/helpers app=$YNH_APP_INSTANCE_NAME if [[ "$app" == "etherpad_mypads" ]]; then ynh_write_var_in_file --file=/var/www/etherpad_mypads/settings.json --key=max --value=100 --after=importExportRateLimiting systemctl restart etherpad_mypads fi ```Triggered at the end of an app installation
This hook is run at the end of the command `yunohost app install` or equivalent action in webadmin. #### Environment variables - YNH_APP_ID: The app id (for example nextcloud) - YNH_APP_INSTANCE_NAME: The app instance name (for example nextcloud__2) - YNH_APP_INSTANCE_NUMBER: The app instance number (for example 2) - YNH_APP_MANIFEST_VERSION: The app manifest version (for example 1 or ?) - YNH_ARCH: The arch as returned by `dpkg --print-architecture` - YNH_APP_ARG_XXXXXXX: The argument of the manifest #### No positionnal arguments #### No waited return #### ExamplesTriggered after removing an app
This hook is run at the end of the command `yunohost app remove` or equivalent action in webadmin. #### Environment variables - YNH_APP_ID: The app id (for example nextcloud) - YNH_APP_INSTANCE_NAME: The app instance name (for example nextcloud__2) - YNH_APP_INSTANCE_NUMBER: The app instance number (for example 2) - YNH_APP_MANIFEST_VERSION: The app manifest version (for example 1 or ?) - YNH_ARCH: The arch as returned by `dpkg --print-architecture` - YNH_APP_PURGE: 1 if the --purge option has been activated #### No positionnal arguments #### No waited return #### ExamplesAdd some files to backup
This hook is run at the end of the command `yunohost backup create` or equivalent action in webadmin. #### Environment variables - YNH_BACKUP_DIR: The work dir in which we can store temporary data to backup like database dump - YNH_BACKUP_CSV: The CSV in which we add the things to backup. Don't use this directly and use ynh_backup helper instead. - YNH_APP_BACKUP_DIR: To document #### Positionnal arguments - $1: The work dir in which we can store temporary data to backup like database dump #### No waited return #### Examples ##### Backup some files in more (for example your custom hooks) ```bash #!/bin/bash # Source YNH helpers source /usr/share/yunohost/helpers ynh_backup_dest (){ YNH_CWD="${YNH_BACKUP_DIR%/}/$1" mkdir -p $YNH_CWD cd "$YNH_CWD" } # Exit hook on subcommand error or unset variable ynh_abort_if_errors # MISC ynh_backup_dest "conf/custom/misc" ynh_backup "/etc/sysctl.d/noipv6.conf" ynh_backup "/usr/local/bin/" ynh_backup "/etc/yunohost/hooks.d/backup/99-conf_custom" ynh_backup "/etc/yunohost/hooks.d/restore/99-conf_custom" ```Restore some files
This hook is run at the end of the command `yunohost backup restore` or equivalent action in webadmin. #### Environment variables - YNH_BACKUP_DIR: The work dir in which we can store temporary data to backup like database dump - YNH_BACKUP_CSV: The CSV in which we add the things to backup. Don't use this directly and use ynh_backup helper instead. #### Positionnal arguments - $1: The work dir in which we can store temporary data to backup like database dump #### No waited return #### Examples ##### restore custom files ```bash #!/bin/bash # Source YNH helpers source /usr/share/yunohost/helpers ynh_restore_dest (){ YNH_CWD="${YNH_BACKUP_DIR%/}/$1" cd "$YNH_CWD" } # Exit hook on subcommand error or unset variable ynh_abort_if_errors # MISC ynh_restore_dest "conf/custom/misc" ynh_restore_file "/etc/sysctl.d/noipv6.conf" ynh_restore_file "/usr/local/bin/" ynh_restore_file "/etc/yunohost/hooks.d/backup/99-conf_custom" ynh_restore_file "/etc/yunohost/hooks.d/restore/99-conf_custom" ```Define a new way to backup and restore files
This hook is run during the command `yunohost backup create` or equivalent action in webadmin. This hook is called several times with different action keywords. #### No environment variables #### Positionnal arguments - $1: The action ("need_mount", "backup", "mount") - $2: The work dir - $3: The name of the backup - $4: The repository in which the backup should be done - $5: An estimation size of the files to backup - $6: A description of the archive #### No waited return #### Examples ##### A very simple backup on rotationnal disks ```bash #!/bin/bash set -euo pipefail work_dir="$2" name="$3" repo="$4" size="$5" description="$6" case "$1" in need_mount) # Set false if your method can itself put files in good place in your archive true ;; backup) mount /dev/sda1 /mnt/hdd if [[ "$(df /mnt/hdd | tail -n1 | cut -d" " -f1)" != "/dev/sda1" ]] then exit 1 fi pushd "$work_dir" current_date=$(date +"%Y-%m-%d_%H:%M") cp -a "${work_dir}" "/mnt/hdd/${current_date}_$name" popd umount /mnt/hdd ;; *) echo "hook called with unknown argument \`$1'" >&2 exit 1 ;; esac exit 0 ```Triggered after reloaded the firewall rules
This hook is run at the end of the command `yunohost firewall reload` or equivalent action in webadmin. #### No environment variables #### Positionnal arguments - $1: True if upnp has succeeded - $2: True if ipv6 is available #### No waited return #### Examples ##### Forbid completely the outgoing 25 port except for postfix user ```bash #!/bin/bash iptables -A OUTPUT -p tcp --dport 25 -m owner --uid-owner postfix -j ACCEPT iptables -A OUTPUT -p tcp --dport 25 -m tcp -j REJECT --reject-with icmp-port-unreachable ```Change configuration suggested as default config in regen-conf mechanism
This hook is run during the command `yunohost tools regen-conf` or equivalent action in webadmin. This hook is called several times with different actions keywords (pre and post operations). In order to be taken into account, the conf_regen hooks must: 1. be present in the folder `/etc/yunohost/hooks.d/conf_regen` 2. follow the naming convention `dd-sss_xxx`. `dd` are 2 digits and should be higher than the ones from the default hook (present in `/usr/share/yunohost/hooks/conf_regen`). `sss` is a string that defines the kind of hook (eg. `ssh` or `postfix`). `xxx` is a free field to help remind what is inside that hook. #### Environment variables - YNH_DOMAINS: The list of domains managed by YunoHost separated by comma - YNH_MAIN_DOMAINS: The list of main domains separated by comma #### Positionnal arguments - $1: The pre or post action - $2: Empty string due to legacy - $3: Empty string due to legacy - $4: In post mode the list of file which should be modified. In pre mode the dir in which we store pending configuration #### No waited return #### Examples ##### Fix the warning about postfix compatibility mode in postfix logs ```bash #!/bin/bash action=$1 pending_dir=$4 postfix_conf=$pending_dir/../postfix/etc/postfix/main.cf [[ "$action" == "pre" ]] || exit 0 [[ -e $postfix_conf ]] || exit 0 echo ' compatibility_level = 2' >> $postfix_conf ```Some conditional HTML code here !
{{/if}}` - For internationalized strings, use `y18n.t('some-string-code')` in the JavaScript, or `{{t 'some-string-code'}}` in the HTML template, and put your string in `locales/en.json`. Don't edit other locales files, this will be done using [Weblate](https://translate.yunohost.org/)! ================================================ FILE: docs/dev/80.core/forms.mdx ================================================ --- title: Technical details for config panel structure and form option types --- Doc auto-generated by [this script](https://github.com/YunoHost/doc/blob/da78370c098ca04b590e18fb1c8924242367703e/scripts/forms_doc_generate.py) on 09/01/2026 (YunoHost version 12.1.39) ## Glossary You may encounter some named types which are used for simplicity. - `Translation`: a translated property - used for properties: `ask`, `help` and `Pattern.error` - a `dict` with locales as keys and translations as values: ```toml ask.en = "The text in english" ask.fr = "Le texte en français" ``` It is not currently possible for translators to translate those string in weblate. - a single `str` for a single english default string ```toml help = "The text in english" ``` - `JSExpression`: a `str` JS expression to be evaluated to `true` or `false`: - used for properties: `visible` and `enabled` - operators availables: `==`, `!=`, `>`, `>=`, `<`, `<=`, `!`, `&&`, `||`, `+`, `-`, `*`, `/`, `%` and `match()` - `Binding`: bind a value to a file/property/variable/getter/setter/validator - save the value in `settings.yaml` when not defined - nothing at all with `"null"` - a custom getter/setter/validator with `"null"` + a function starting with `get__`, `set__`, `validate__` in `scripts/config` - a variable/property in a file with `:__FINALPATH__/my_file.php` - a whole file with `__FINALPATH__/my_file.php` - `Pattern`: a `dict` with a regex to match the value against and an error message ```toml pattern.regexp = '^[A-F]\d\d$' pattern.error = "Provide a room number such as F12: one uppercase and 2 numbers" # or with translated error pattern.error.en = "Provide a room number such as F12: one uppercase and 2 numbers" pattern.error.fr = "Entrez un numéro de salle comme F12: une lettre majuscule et deux chiffres." ``` - IMPORTANT: your `pattern.regexp` should be between simple quote, not double. ## Configuration panel structure ### ConfigPanel This is the 'root' level of the config panel toml file #### Examples ```toml version = 1.0 [config] # …refer to Panels doc ``` #### Properties - `version`: `float` (default: `1.0`), version that the config panel supports in terms of features. - `i18n` (optional): `str`, an i18n property that let you internationalize options text. - However this feature is only available in core configuration panel (like `yunohost domain config`), prefer the use `Translation` in `name`, `help`, etc. --- ### Panel Panels are, basically, sections grouped together. Panels are `dict`s defined inside a ConfigPanel file and require a unique id (in the below example, the id is `main`). Keep in mind that this id will be used in CLI to refer to the panel, so choose something short and meaningfull. #### Examples ```toml [main] name.en = "Main configuration" name.fr = "Configuration principale" help = "" services = ["__APP__", "nginx"] [main.customization] # …refer to Sections doc ``` #### Properties - `name`: `Translation` or `str`, displayed as the panel title - `help` (optional): `Translation` or `str`, text to display before the first section - `services` (optional): `list` of services names to `reload-or-restart` when any option's value contained in the panel changes - `"__APP__` will refer to the app instance name - `actions`: FIXME not sure what this does --- ### Section Sections are, basically, options grouped together. Sections are `dict`s defined inside a Panel and require a unique id (in the below example, the id is `customization` prepended by the panel's id `main`). Keep in mind that this combined id will be used in CLI to refer to the section, so choose something short and meaningfull. Also make sure to not make a typo in the panel id, which would implicitly create an other entire panel. If at least one `button` is present it then become an action section. Options in action sections are not considered settings and therefor are not saved, they are more like parameters that exists only during the execution of an action. FIXME i'm not sure we have this in code. #### Examples ```toml [main] [main.customization] name.en = "Advanced configuration" name.fr = "Configuration avancée" help = "Every form items in this section are not saved." services = ["__APP__", "nginx"] [main.customization.option_id] type = "string" # …refer to Options doc ``` #### Properties - `name` (optional): `Translation` or `str`, displayed as the section's title if any - `help`: `Translation` or `str`, text to display before the first option - `services` (optional): `list` of services names to `reload-or-restart` when any option's value contained in the section changes - `"__APP__` will refer to the app instance name - `optional`: `bool` (default: `true`), set the default `optional` prop of all Options in the section - `visible`: `bool` or `JSExpression` (default: `true`), allow to conditionally display a section depending on user's answers to previous questions. - Be careful that the `visible` property should only refer to **previous** options's value. Hence, it should not make sense to have a `visible` property on the very first section. --- ## List of all option types ### Common properties Options are fields declaration that renders as form items, button, alert or text in the web-admin and printed or prompted in CLI. They are used in app manifests to declare the before installation form and in config panels. [Have a look at the app config panel doc](/dev/packaging/advanced/config_panels) for details about Panels and Sections. ! IMPORTANT: as for Panels and Sections you have to choose an id, but this one should be unique in all this document, even if the question is in an other panel. #### Example ```toml [section.my_option_id] type = "string" # ask as `str` ask = "The text in english" # ask as `dict` ask.en = "The text in english" ask.fr = "Le texte en français" # advanced props visible = "my_other_option_id != 'success'" readonly = true # much advanced: config panel only? bind = "null" ``` #### Properties - `type`: the actual type of the option, such as 'markdown', 'password', 'number', 'email', ... - `ask`: `Translation` (default to the option's `id` if not defined): - text to display as the option's label for inputs or text to display for readonly options - in config panels, questions are displayed on the left side and therefore have not much space to be rendered. Therefore, it is better to use a short question, and use the `help` property to provide additional details if necessary. - `visible` (optional): `bool` or `JSExpression` (default: `true`) - define if the option is diplayed/asked - if `false` and used alongside `readonly = true`, you get a context only value that can still be used in `JSExpression`s - `readonly` (optional): `bool` (default: `false`, forced to `true` for readonly types): - If `true` for input types: forbid mutation of its value - `bind` (optional): `Binding`, config panels only! A powerful feature that let you configure how and where the setting will be read, validated and written - if not specified, the value will be read/written in the app `settings.yml` - if `"null"`: - the value will not be stored at all (can still be used in context evaluations) - if in `scripts/config` there's a function named: - `get__my_option_id`: the value will be gathered from this custom getter - `set__my_option_id`: the value will be passed to this custom setter where you can do whatever you want with the value - `validate__my_option_id`: the value will be passed to this custom validator before any custom setter - if `bind` is a file path: - if the path starts with `:`, the value be saved as its id's variable/property counterpart - this only works for first level variables/properties and simple types (no array) - else the value will be stored as the whole content of the file - you can use `__FINALPATH__` or `__INSTALL_DIR__` in your path to point to dynamic install paths - FIXME are other global variables accessible? - [refer to `bind` doc for explaination and examples](/dev/packaging/advanced/config_panels#the-bind-statement) --- ### Common inputs properties Rest of the option types available are considered `inputs`. #### Example ```toml [section.my_option_id] type = "string" # …any common props… + optional = false redact = false default = "some default string" help = "You can enter almost anything!" example = "an example string" placeholder = "write something…" ``` #### Properties - [common properties](#common-properties) - `optional`: `bool` (default: `false`, but `true` in config panels) - `redact`: `bool` (default: `false`), to redact the value in the logs when the value contain private information - `default`: depends on `type`, the default value to assign to the option - in case of readonly values, you can use this `default` to assign a value (or return a dynamic `default` from a custom getter) - `help` (optional): `Translation`, to display a short help message in cli and web-admin - `example` (optional): `str`, to display an example value in web-admin only - `placeholder` (optional): `str`, shown in the web-admin fields only --- ### `markdown` (readonly) Display markdown multi-line content. Markdown is currently only rendered in the web-admin #### Example ```toml [section.my_option_id] type = "display_text" ask = "Text **rendered** in markdown." ``` #### Properties - [common properties](#common-properties) --- ### `alert` (readonly) Alerts displays a important message with a level of severity. You can use markdown in `ask` but will only be rendered in the web-admin. #### Example ```toml [section.my_option_id] type = "alert" ask = "The configuration seems to be manually modified..." style = "warning" icon = "warning" ``` #### Properties - [common properties](#common-properties) - `style`: any of `"success|info|warning|danger"` (default: `"info"`) - `icon` (optional): any icon name from [Fork Awesome](https://forkaweso.me/Fork-Awesome/icons/) - Currently only displayed in the web-admin --- ### `button` (readonly) Triggers actions. Available only in config panels. Renders as a `button` in the web-admin and can be called with `yunohost [app|domain|settings] action run(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(par ex. carte ARM, ancien ordinateur)
derrière un VPN
(VPS ou serveur dédié)
(e.g. a Raspberry Pi)
(par ex. un Raspberry Pi)
(electricity)
(VPN)
(VPS)
(électricité)
(VPN)
(VPS)
(see here)
(voir ici)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(ex. placa ARM ou computadora antiga)
detrás dunha VPN
(VPS ou dedicado)
(e.g. a Raspberry Pi)
(ex. Raspberry Pi)
(electricity)
(VPN)
(VPS)
(electricidade)
(VPN)
(VPS)
(see here)
(le isto)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
(e.g. ARM board, old computer)
behind a VPN
(VPS or dedicated)
(e.g. a Raspberry Pi)
(electricity)
(VPN)
(VPS)
(see here)
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/ca.po ================================================ # Copyright (C) 2025 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation package. # # Weblate Admin
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/de.po ================================================ # Copyright (C) 2025 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation. # # Languages add-on
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/en.pot ================================================ # Copyright (C) 2026 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation package. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: YunoHost documentation VERSION\n" "POT-Creation-Date: 2026-01-04 16:21+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/es.po ================================================ # Copyright (C) 2025 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation. # # Languages add-on
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/eu.po ================================================ # Copyright (C) 2025 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation package. # # Weblate Admin
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/fr.po ================================================ # Copyright (C) 2025 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation. # # Languages add-on
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" "| Registrar | Compatibilité | Facilité d'obtention d'une clé API | Mode d'emploi |\n" "|------------------------------------ -|-----------------------------|---------------------------|-------|\n" "| [Gandi](https://www.gandi.net) | ✘ (ne fonctionne pas) | ✘ | [Obtenir une clé API](/admin/get_started/providers/registrar/gandi)
[Voir le bug ici](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (testé) | ✘ | [Obtenir une clé API](/admin/get_started/providers/registrar/ovh/autodns)
[Configurer manuellement](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (dans le catalogue mais non testé) | ✘✘✘ API non disponible sans 50 $ sur le compte | [Obtenir une clé API](/admin/get_started/providers/registrar/namecheap) |\n" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/gl.po ================================================ # Copyright (C) 2025 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation package. # # "José M."
[See bug here](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configure manually](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/admin/get_started/providers/registrar/namecheap) |\n" msgstr "" "| Rexistradora | Compatibilidade | Facilidade para obter clave API | Procedemento |\n" "|-------------------------------------|-----------------------------|---------------------------|-------|\n" "| [Gandi](https://www.gandi.net) | ✘ (broken) | ✘ | [Obter clave da API](/admin/get_started/providers/registrar/gandi)
[Ver incidencias](https://github.com/YunoHost/issues/issues/2419) |\n" "| [OVH](https://ovh.com/domaines) | ✔ (tested) | ✘ | [Obtain an API key](/admin/get_started/providers/registrar/ovh/autodns)
[Configurar a man](/admin/get_started/providers/registrar/ovh/manualdns) |\n" "| [Namecheap](https://namecheap.com) | ✘ (na referencia, pero sen probar) | ✘✘✘ API se non tes 50$ na conta | [Obter clave da API](/admin/get_started/providers/registrar/namecheap) |\n" ================================================ FILE: i18n/docs/admin/05.get_started__10.providers__05.registrar__index/id.po ================================================ # Copyright (C) 2025 YunoHost Contributors # This file is distributed under the same license as the YunoHost documentation package. # # Weblate Admin