diff --git a/docs/admin/05.get_started/10.providers/05.registrar/ovh/manualdns.mdx b/docs/admin/05.get_started/10.providers/05.registrar/ovh/manualdns.mdx index e11010f8b2..4d9f694e6f 100644 --- a/docs/admin/05.get_started/10.providers/05.registrar/ovh/manualdns.mdx +++ b/docs/admin/05.get_started/10.providers/05.registrar/ovh/manualdns.mdx @@ -13,7 +13,7 @@ Click on the **DNS Zone** tab, then on **Add an entry**: ![OVH website screenshot](/img/providers/ovh_dns_zone.png?resize=800) -Now you need to add the DNS redirections as specified by the [standard DNS zone configuration](/admin/get_started/post_install/dns_config) +Now you need to add the DNS redirections as specified in the [DNS configuration page](/admin/domains/dns_configuration). Click on "Change in text format", keep the first four lines: @@ -24,7 +24,7 @@ $TTL 3600 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). +then erase everything below, and replace it with the configuration generated by YunoHost as explained in [this page](/admin/domains/dns_configuration). ### Dynamic IP diff --git a/docs/admin/05.get_started/20.install_on/_configuration.mdx b/docs/admin/05.get_started/20.install_on/_configuration.mdx index e49f97c896..e07a4ef4be 100644 --- a/docs/admin/05.get_started/20.install_on/_configuration.mdx +++ b/docs/admin/05.get_started/20.install_on/_configuration.mdx @@ -52,13 +52,42 @@ If you want to create subdomains, do not forget to add them in the `hosts` file ``` -This will be the domain used by your server's users to access the **authentication portal**. You can later add other domains, and change which one is the main domain if needed. +This will be the domain used by your server's users to access the **authentication portal**. -- If you're new to self-hosting and do not already have a domain name, we recommend using a **.nohost.me** / **.noho.st** / **.ynh.fr** (e.g. `homersimpson.nohost.me`). Provided that it's not already taken, the domain will be configured automatically and you won't need any further configuration step. Please note that the downside is that you won't have full-control over the DNS configuration. -- If you already own a domain name, you probably want to use it here. You will later need to configure DNS records as explained [here](/admin/get_started/post_install/dns_config). +You should be presented with 3 options (reviewed [in details here](/admin/domains)): + +
+ YunoHost's free domains + + If you're new to self-hosting and do not already have a domain name, we recommend using the free domain provided by YunoHost. + You get multiple base domain choices: `.nohost.me` / `.noho.st` / `.ynh.fr` for + which you must specify the subdomain you want to use (e.g. `homersimpson.nohost.me`). + + Provided that it's not already taken, the domain will be configured automatically and you won't need any further configuration steps + (but as a downside you won't have full control over its DNS configuration). + + [more details on YunoHost's free domains](/admin/domains/dns_nohost_me) +
+ +
+ Your own domain + + If you already own a domain name, you probably want to use it here. You will later need to configure DNS records as explained [here](/admin/domains/dns_configuration). + + You can also configure a [subdomain](https://en.wikipedia.org/wiki/Subdomain) if your + main domain is already in use for other services. +
+ +
+ Local domains + + Because yes, you *have to* configure a domain name. And if none of the above options are + satisfying, you can set up a dummy domain such as `yolo.test` and tweak your **local** `/etc/hosts` file such that this dummy domain [points to the appropriate IP, as explained here](/admin/tutorials/domains/dns_local_network). +
:::tip -Yes, you *have to* configure a domain name. If you don't have any domain name and don't want a **.nohost.me** / **.noho.st** / **.ynh.fr** either, you can set up a dummy domain such as `yolo.test` and tweak your **local** `/etc/hosts` file such that this dummy domain [points to the appropriate IP, as explained here](/admin/tutorials/domains/dns_local_network). +This choice can be modified later, by adding other domains, changing which one is the main domain, +or set specific applications to run on a different domain. ::: ### First user @@ -74,7 +103,7 @@ Once the postinstall is done, you should be able to actually log in the web admi The diagnosis system is meant to provide an easy way to validate that all critical aspects of your server are properly configured - and guide you in how to fix issues. The diagnosis will run twice a day and send an alert if issues are detected. :::tip -**Don't run away** ! The first time you run the diagnosis, it is quite expected to see a bunch of yellow/red alerts because you typically need to [configure DNS records](/admin/get_started/post_install/dns_config) (if not using a `.nohost.me`/`noho.st`/`ynh.fr` domain), add a swapfile if not enough ram as well as [port forwarding](/admin/get_started/post_install/port_forwarding) on your home's router. +**Don't run away** ! The first time you run the diagnosis, it is quite expected to see a bunch of yellow/red alerts because you typically need to [configure DNS records](/admin/get_started/post_install/dns_config), add a swapfile if not enough ram as well as [port forwarding](/admin/get_started/post_install/port_forwarding) on your home's router. ::: :::tip diff --git a/docs/admin/05.get_started/40.post_install/20.dns_config.mdx b/docs/admin/05.get_started/40.post_install/20.dns_config.mdx index c7c8f73b13..e58c4293bc 100644 --- a/docs/admin/05.get_started/40.post_install/20.dns_config.mdx +++ b/docs/admin/05.get_started/40.post_install/20.dns_config.mdx @@ -1,112 +1,14 @@ --- -title: DNS zone configuration +title: Post-install domain configuration description: "Add a domain for easier access" --- -DNS (domain name system) is a system that converts human-readable addresses -(domain names) into machine-understandable addresses (IP). For your server to be -easily accessible by human beings, and for some services like mail to work -properly, DNS must be configured. +Depending on the domain you picked during post-install you may have a few configuration +steps left. -If you're using an [automatic domain](/admin/tutorials/domains/dns_nohost_me) provided by the YunoHost Project, the configuration should be -performed automatically. If you're using your own domain name (e.g. bought via -a registrar), you should manually configure your domain on your registrar's -interface. +- If you picked one of YunoHost free domain (`nohost.me`, `noho.st`, `ynh.fr`) everything + is automatic and you should be good to go. -## Recommended DNS configuration +- If you picked a custom domain option you want to have a look at [DNS Configuration](/admin/domains/dns_configuration). -NB: Examples here use the placeholder `your.domain.tld`, you have to replace it with your real domain, such as `www.yunohost.org`. - -YunoHost provides a recommended DNS configuration, available via: - -- the webadmin, in Domain > your.domain.tld > DNS configuration; -- or the command line, `yunohost domain dns suggest your.domain.tld` - -For specific needs or specific setups, and if you know what you're doing, you -might want or have to tweak these, or add additional ones (e.g. to handle -subdomains). - -The recommended configuration typically looks like this: - -```bash -# -# Basic ipv4/ipv6 records -# -@ 3600 IN A 111.222.33.44 -* 3600 IN A 111.222.33.44 - -# (If your server is IPv6 capable, there are some AAAA records) -@ 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111 -* 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111 - -# -# XMPP -# -_xmpp-client._tcp 3600 IN SRV 0 5 5222 your.domain.tld. -_xmpp-server._tcp 3600 IN SRV 0 5 5269 your.domain.tld. -muc 3600 IN CNAME @ -pubsub 3600 IN CNAME @ -vjud 3600 IN CNAME @ -xmpp-upload 3600 IN CNAME @ - -# -# Mail (MX, SPF, DKIM and DMARC) -# -@ 3600 IN MX 10 your.domain.tld. -@ 3600 IN TXT "v=spf1 a mx -all" -mail._domainkey 3600 IN TXT "v=DKIM1; k=rsa; p=someHuuuuuuugeKey" -_dmarc 3600 IN TXT "v=DMARC1; p=none" -``` - -Though it might be easier to understand it if displayed like this: - -| Type | Name | Value | -| :-----: | :--------------------: | :--------------------------------------------------: | -| **A** | **@** | `111.222.333.444` (your IPv4) | -| A | * | `111.222.333.444` (your IPv4) | -| AAAA | @ | `2222:444:8888:3333:bbbb:5555:3333:1111` (your IPv6) | -| AAAA | * | `2222:444:8888:3333:bbbb:5555:3333:1111` (your IPv6) | -| **SRV** | **_xmpp-client._tcp** | `0 5 5222 your.domain.tld.` | -| **SRV** | **_xmpp-server._tcp** | `0 5 5269 your.domain.tld.` | -| CNAME | muc | `@` | -| CNAME | pubsub | `@` | -| CNAME | vjud | `@` | -| CNAME | xmpp-upload | `@` | -| **MX** | **@** | `your.domain.tld.` (and priority: 10) | -| TXT | @ | `"v=spf1 a mx -all"` | -| TXT | mail._domainkey | `"v=DKIM1; k=rsa; p=someHuuuuuuugeKey"` | -| TXT | _dmarc | `"v=DMARC1; p=none"` | - -### A few notes about this table - -- Not all these lines are absolutely necessary. For a minimal setup, you only need the records in bold. -- The dot at the end of `your.domain.tld.` is important ;); -- `@` corresponds to `your.domain.tld`, and e.g. `muc` corresponds to `muc.your.domain.tld`; -- These are example values ! See your generated conf for the actual values you should use; -- We recommend a [TTL](https://en.wikipedia.org/wiki/Time_to_live#DNS_records) of 3600 (1 hour). But you can use something else if you know what you're doing; -- Don't put an IPv6 record if you're not sure IPv6 really works on your server! You might have issues with Let's Encrypt if it doesn't. -- If you're using the domain provider Namecheap the SRV DNS entries are formatted as **Service**: `_xmpp-client` **Protocol**: `_tcp` **Priority**: `0` **Weight**: `5` **Port**: `5222` **Target**: `your.domain.tld` - -### Reverse DNS - -If your ISP or VPS provider let you define a [Reverse DNS -lookup](https://en.wikipedia.org/wiki/Reverse_DNS_lookup) for your public IPv4 -and/or IPv6 addresses, you must configure it. It will prevent you to be marked as -spam by anti-spam filters. - -**N.B.: the reverse DNS configuration happens on your Internet Service Provider or VPS provider. It is *not* handled by your domain's registrar.** - -If your public IPv4 address is `111.222.333.444` and your DNS -domain is `domain.tld`, you should get following answer when using `nslookup` -command tool: - -```bash -nslookup 111.222.333.444 -444.333.222.111.in-addr.arpa name = domain.tld. -``` - -The diagnosis system available in the webadmin performs this checks automatically (in section Email). - -### Dynamic IP - -If your global IP address is constantly changing, follow this [tutorial](/admin/tutorials/domains/dns_dynamicip). +If you want to change the main domain you picked, have a look at [Domain](/admin/domains). \ No newline at end of file diff --git a/docs/admin/25.domains/dns_configuration.mdx b/docs/admin/25.domains/dns_configuration.mdx new file mode 100644 index 0000000000..1ba18742fc --- /dev/null +++ b/docs/admin/25.domains/dns_configuration.mdx @@ -0,0 +1,167 @@ +--- +title: DNS Configuration +--- + +DNS (domain name system) is a system that converts human-readable addresses +(domain names) into machine-understandable addresses (IP). For your server to be +easily accessible by human beings, and for some services like mail to work +properly, DNS must be configured. + +If you're using an [automatic domain](/admin/domains/dns_nohost_me) provided by the YunoHost Project, the configuration should be +performed automatically. If you're using your own domain name (e.g. bought via +a registrar), this page should explain how to manually configure your domain on your +registrar's interface. + +Note YunoHost supports the [automatic configuration of DNS records](/admin/domains/#dns-configuration) for some registrar. + +## A brief explanation of domain names + +Because understanding domains can be tricky, it might be worth detailing how they work. + +A domain is a human-readable address made out of *labels* concatenated by dots. + +So if you take the domain name `www.yunohost.org` the usual convention is to break it down as: + +| domain | description | +| :---------------: | :--------------------: | +| `.org` | top-level domain | +| `yunohost.org` | apex/root/bare domain | +| `www.yunohost.org` | subdomain | + +However from [Wikipedia](https://en.wikipedia.org/wiki/Domain_name) we can learn: + +> *Domain names are organized in subordinate levels (subdomains) of the DNS root domain, which is nameless.* + +So in theory `yunohost.org` is a subdomain of `.org` but for convenience we usually +talk about *subdomain* for any domain that has 2 levels after the top-level domain. +This become even more confusing if you consider that some top-level domains have 2 labels +(e.g. `.gouv.fr` or `.co.uk`). + +The wikipedia quote also mention the "DNS root domain" which is usually omitted but +when not, is represented by a single dot at the end. This form is referred to as +"fully qualified domain name" (FQDN). With our previous example, `www.yunohost.org.` would be an FQDN. +This is good to remember because you usually need to specify an FQDN in your DNS records. + +## A brief explanation of DNS records. + +:::info +DNS records must be managed through your registrar's interface (the vendor you rent your custom domain from). +::: + +In the following explanations you can assume the examples in code blocks use the +DNS [zone file](https://en.wikipedia.org/wiki/Zone_file) syntax. The lines we use +have 5 columns separated by a whitespace. Those columns represent the different record's fields: + +| name | ttl | record class | record type | record data | +| ---- | --- | ------------ | ----------- | ----------- | + +It's also good to be aware of the following: + +- We use placeholder values in the examples ! replace with the appropriate ones for your case. +- We recommend a [TTL](https://en.wikipedia.org/wiki/Time_to_live#DNS_records) of 3600s (1 hour). But you can use something else if you know what you're doing. +- Don't put an IPv6 record if you're not sure IPv6 really works on your server ! You might have issues with *Let's Encrypt* if it doesn't. +- The `@` name corresponds to the origin, which is your apex domain name (like `mydomain.tld`) +- Reminder that a domain specified in the data of the record **needs to end with a dot** (to be an FQDN as explained previously). + +## Minimal DNS configuration + +When registering a custom domain name through the YunoHost interface, this is the minimal +required configuration to have it working. + +```autohotkey +;; standard IPv4 record +@ 3600 IN A 111.222.33.44 + +;; if your server is IPv6 capable you can add an AAAA record +@ 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111 +``` + +However, this doesn't allow all features to work and you will notice warnings and errors +when running the *Diagnosis* in the web interface. + + +## Recommended DNS configuration + +YunoHost provides a recommended DNS configuration, available via: + +- the webadmin, in `Domains` > `{yourdomain.tld}` > `DNS`; +- or the command line, `yunohost domain dns suggest yourdomain.tld` + +For specific needs or specific setups, and if you know what you're doing, you +might want or have to tweak these, or add additional ones (e.g. to handle +subdomains). + +The recommended configuration typically looks like this: + +```autohotkey +;; standard IPv4 records +@ 3600 IN A 111.222.33.44 +* 3600 IN A 111.222.33.44 + +;; if your server is IPv6 capable you can add AAAA records +@ 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111 +* 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111 + +;; Mail (MX, SPF, DKIM and DMARC) +@ 3600 IN MX 10 mydomain.tld. +@ 3600 IN TXT "v=spf1 a mx -all" +mail._domainkey 3600 IN TXT "v=DKIM1; k=rsa; p=someHuuuuuuugeKey" +_dmarc 3600 IN TXT "v=DMARC1; p=none" +``` + + +## Subdomains + +YunoHost allows the use of subdomains. If you rent a domain name `mydomain.com`, +you can create a subdomain `blog.mydomain.com`. + +```autohotkey +@ 3600 IN A 111.222.33.44 +@ 3600 IN AAAA 2222:444:8888:3333:bbbb:5555:3333:1111 +* 3600 IN CNAME mydomain.com. +agenda 3600 IN CNAME mydomain.com. +blog 3600 IN CNAME mydomain.com. +rss 3600 IN CNAME mydomain.com. +``` + +The above allow you to access `agenda.mydomain.com`, `blog.mydomain.com` and `rss.mydomain.com` subdomains. + +However you might be in the position where your apex domain is already in use for another service +(the `@ A` record is already in use). +In that case you might want to have this DNS configuration instead: + +```autohotkey +agenda 3600 IN A XYZ.XYZ.XYZ.XYZ +agenda 3600 IN AAAA 1234:1234:1234:FFAA:FFAA:FFAA:FFAA:AAFF +blog 3600 IN A XYZ.XYZ.XYZ.XYZ +blog 3600 IN AAAA 1234:1234:1234:FFAA:FFAA:FFAA:FFAA:AAFF +rss 3600 IN A XYZ.XYZ.XYZ.XYZ +rss 3600 IN AAAA 1234:1234:1234:FFAA:FFAA:FFAA:FFAA:AAFF +``` + +## Reverse DNS + +If your ISP or VPS provider let you define a [Reverse DNS +lookup](https://en.wikipedia.org/wiki/Reverse_DNS_lookup) for your public IPv4 +and/or IPv6 addresses, you must configure it. It will prevent you to be marked as +spam by anti-spam filters. + +:::note +The reverse DNS configuration happens on your Internet Service Provider or VPS provider. It is NOT handled by your domain's registrar. +::: + +If your public IPv4 address is `111.222.333.444` and your DNS +domain is `mydomain.tld`, you should get following answer when using `nslookup` +command tool: + +```bash +nslookup 111.222.333.444 +444.333.222.111.in-addr.arpa name = mydomain.tld. +``` + +From the web interface, you can run the *Diagnosis* and check in the *Email* section +if reverse DNS is configured, and if not to which value it must be set to. + +## Dynamic IP + +If your global IP address is constantly changing, [follow this tutorial](/admin/tutorials/domains/dns_dynamicip). diff --git a/docs/admin/25.domains/dns_nohost_me.mdx b/docs/admin/25.domains/dns_nohost_me.mdx new file mode 100644 index 0000000000..6c9c741e96 --- /dev/null +++ b/docs/admin/25.domains/dns_nohost_me.mdx @@ -0,0 +1,91 @@ +--- +title: YunoHost's free domains +--- + +In order to make self-hosting as accessible as possible, the YunoHost Project provides +a *free* and *automatically configured* domain name service. By using this service, +you won't have to [configure DNS records](/admin/domains/dns_configuration) yourself, +which can be tedious and technical. + +This service is offered during the post-installation setup, but check the +[Creating a domain after the post-installation](#creating-a-free-domain-after-the-post-installation) +section below for usage afterwards. + +During creation of the domain you are prompted to choose a *base domain* and a unique *subdomain* you want to use. +The following *base domains* are offered: + +- `nohost.me` +- `noho.st` +- `ynh.fr` + +> For example you may choose to end up with the `frogenjoyer.nohost.me` subdomain. + + +:::info +To limit resources costs and abuses, each instance may only have one of these domain +setup at any given time. +::: + +### Creating additional subdomains + +Even after creating your subdomain, you can prepend more subdomain to it, allowing +your applications to each have an unique subdomain if desired (which is also +a workaround for the one free domain per instance). + +> For example you picked the `frogenjoyer.ynh.fr` subdomain. For a blog application, you +> can create an additional `blog.frogenjoyer.ynh.fr` subdomain. +> There's no limit so you could also create a `pond.place.frogenjoyer.ynh.fr` subdomain ! + +### Creating a free domain after the post-installation + + + +If you already did the post-install and want to add a free domain, you may do so +from the *Domains* web interface, selecting the option "I don't have a domain name...". + + +Alternatively, the following commands can be used. + +Add the domain +```bash +yunohost domain add frogenjoyer.nohost.me +``` +At this step, you should be prompted for a DynDNS recovery password, this password could be used to reset your dyndns free domain in order to register it again on an other yunohost, or during a reinstallation. + +(optional) Set it as the main domain +``` +yunohost domain main-domain -n frogenjoyer.nohost.me +``` + + + +### Retrieving an existing free domain + +If you reinstall your server and want to use a domain already used previously, follow the +creation process as you would if it was new (so use the same subdomain label). However, +in the password field enter the password you have defined when creating the +domain in the past. + +If you forgot your password you may need to [request a manual domain reset](https://forum.yunohost.org/t/nohost-domain-recovery/442). + +:::note +The password feature is available since YunoHost 11.2, previously you would need to +use the [dedicated forum thread](https://forum.yunohost.org/t/nohost-domain-recovery/442). +::: + +### Changing your free domain + +If you wish to use a different free domain, you first have to remove your present domain registration: + +- using the web interface > `Domains` > `{yourdomain.tld}` > `delete` button + +:::note +You can check the "Also unregister" option to permanently free the domain; otherwise +you can still re-use it with the password set on creation. +::: + +![A screenshot of the delete dialog for automatic domains](/img/webadmin/webadmin_domain_remove_dyndns.png) + +- from the command line using `yunohost domain remove` + +You may then add a new domain. diff --git a/docs/admin/25.domains/index.mdx b/docs/admin/25.domains/index.mdx index 93260168d5..fa96111f59 100644 --- a/docs/admin/25.domains/index.mdx +++ b/docs/admin/25.domains/index.mdx @@ -9,36 +9,24 @@ YunoHost lets you manage and serve multiple domains on a single server. So you c Domains can be managed in the 'Domains' section of the webadmin, or via the `yunohost domain` category of the command line. -Whenever you add a domain, it is assumed that you have purchased (or at least control) the domain, so that you can manage its [DNS configuration](/admin/get_started/post_install/dns_config). An exception is [domains in `.nohost.me`, `.noho.st` and `ynh.fr`](/admin/tutorials/domains/dns_nohost_me) which are offered by the YunoHost Project, and can be directly integrated with YunoHost through automatic DynDNS configuration. To limit abuse and costs, an instance can only have one domain offered at a time, but you can add as many sub-domains to it as you like. For example, if you choose `example.ynh.co.uk` you can then add the domains `video.example.ynh.co.uk` or `www.exemple.ynh.fr` or any other sub-domain you may require. - -Domains can be managed in the 'Domain' section of the webadmin, or through the `yunohost domain` category of the command line. - ![A screenshot of the webadmin domain interface with an "Add domain" button and a list of domains](/img/webadmin/webadmin_domain.png) -## 3 types of domains - - - - -In order to make self-hosting as accessible as possible, the YunoHost Project provides a *free* and *automatically configured* domain name service. By using this service, you won't have to [configure DNS records](/admin/get_started/post_install/dns_config) yourself, which can be tedious and technical. +## Adding a new domain -The following (sub)domains are offered: +When registering domains on your instance, you are being presented with 4 options: -- `whateveryouwant.nohost.me`; -- `whateveryouwant.noho.st`; -- `whateveryouwant.ynh.fr`. + + -In more, YunoHost uses an integrated dynamic DNS mechanism, so your server can stay reachable even if your public IP change. +In order to make self-hosting as accessible as possible, the YunoHost Project provides a *free* and *automatically configured* domain name service. By using this service, you won't have to configure DNS records yourself, which can be tedious and technical. -To get one of this domain you simply need to choose `I don't have a domaine name…` during the initial configuration (postinstall) or on the `Add domain` page. +The following base domains are offered: `nohost.me`, `noho.st`, `ynh.fr`. -![Here a screenshot of the "Add domain" page where you can choose "I don't have a domain name"](/img/webadmin/webadmin_dyndns.png) +[Learn more about YunoHost's free domain here](/admin/domains/dns_nohost_me). -:::info -To limit resources costs and abuses, each instance may only have one of these domains setup at any given time, however you can add as many sub-domains of it as you wish. For example, if you choose `example.noho.st` you can later add the domains `video.example.noho.st` or `www.example.ynh.noho.st` or any other sub-domain you may need. In this case you need to select `I already have a domain name`. -::: +To get one of this domain you simply need to choose `I don't own a domaine name…` option. -[More information on this domains](/admin/tutorials/domains/dns_nohost_me) +![A screenshot of the "Add domain" page where you can choose "I don't own a domain, I want to register/use a free DynDNS domain provided by the YunoHost project"](/img/webadmin/webadmin_dyndns.png) @@ -48,22 +36,37 @@ Having your own domain brings several advantages: - more control and autonomy - simpler domain name (for example directly in .net or .org) -However, you have to pay for it each year (about 15€/year ... depending on the TLD) and you have to do some extra configuration to [setup a correct DNS zone](/admin/get_started/post_install/dns_config). Our diagnosis tool can trigger alert to help you to do this configuration. +However, you have to pay for it each year (about 15€/year ... depending on the TLD) and you have to do some extra configuration to [setup a correct DNS zone](/admin/domains/dns_configuration). Our diagnosis tool can trigger alert to help you to do this configuration. +If you don't have a custom domain yet, we suggest you to buy it from a [registrar whose API is supported by YunoHost](/admin/get_started/providers/registrar/) to simplify and automate the DNS configuration. + +[Learn more about DNS configuration here](/admin/domains/dns_configuration) -If you already have your own domain, you can simply click "I already have a domain name…". If you don't, in order to simplify and automate the DNS configuration, we suggest you to buy it from a [registrar whose API is supported by YunoHost](/admin/get_started/providers/registrar/). +This option corresponds to the `I want to add a domain I own` option in the web interface: -![Here a screenshot of the "Add domain" page where you can choose "I already have a domain name"](/img/webadmin/webadmin_domain_owndomain.png) +![A screenshot of the "Add domain" page where you can choose "I want to add a domain I own"](/img/webadmin/webadmin_domain_owndomain.png) -[Know more on DNS zone configuration](/admin/get_started/post_install/dns_config) + + + +A subdomain allow you to prepend multiple labels to existing domains you own. This +is especially convenient for applications, as you can define an unique subdomain for +each of them. + +> Example, you previously added the custom domain `bonjour.fr`; you can create +> multiple subdomain at `blog.bonjour.fr`, `cloud.bonjour.fr`, and so on. + +[Learn more about subdomains here](/admin/domains/dns_configuration/#a-brief-explanation-of-domain-names). + +This option corresponds to the `I want to add a subdomain of an already added domain` option in the web interface: + +![A screenshot of the "Add domain" page where you can choose "I want to add a subdomain of an already added domain"](/img/webadmin/webadmin_domain_subdomain.png) - + Starting from YunoHost v4.3, domains ending by `.local` are fully supported, in addition to the default `yunohost.local`. They do not use the DNS protocol, but the mDNS one (also known as Zeroconf, Bonjour), which allows them to be published with no specific configuration but exclusively on your local network or VPN. -Their use is this especially suitable when you do not need your apps to be available on the Internet. - -![Here a screenshot of the "Add domain" page where you can choose "I already have a domain name" and setup your domain ending by .local](/img/webadmin/webadmin_domain_local.png) +Their use is especially suitable when you do not need your apps to be available on the Internet. :::info mDNS protocol does not allow for subdomains to be created. So `domain.local` will work, while `sub.domain.local` is not possible. @@ -81,14 +84,54 @@ Unfortunately, Android devices before version 12 (released in 2021) do not seem To be able to reach `.local` domains on your Android devices, you will have to add in their DNS settings your YunoHost server's local IP address. ::: +This option corresponds to the `I want a domain for local usage / test only` option in the web interface: + +![Here a screenshot of the "Add domain" page where you can choose "I want a domain for local usage / test only"](/img/webadmin/webadmin_domain_local.png) + + + +## Installing an application on a domain + +During the installation of an application, you are being prompted to which domain the +application must be configured to. + +Even if you teh domain can be later changed, it is recommended you register the domain in +your instance before installing the application. + +:::tip +It is common to install the application on a subdomain, but this is personal preferences. + +> Example: `blog.mydomain.tld` instead of using `mydomain.tld` or `mydomain.tld/blog` +::: + + +## Changing an application assigned domain. + +You can change the application domain: + +- through the web interface > `Applications` > `{app name}` > `Operations` +- through the command line with `yunohost app change-url` + +:::note +Some applications do not allow you to change domains. In general, it is still possible to make the change manually, but this operation requires a variety of system administration skills. +::: + ## DNS configuration -DNS (Domain Name System) is a system that enables computers worldwide to translate human-readable domain names (such as `yolo.com`) into machine-readable IP addresses (such as `11.22.33.44`). For this translation (and other features) to work, DNS records need to be carefully configured. +Once a domain is added, you may need to manage its DNS configuration. + +[Learn more about DNS configuration here](/admin/domains/dns_configuration). + +YunoHost can help you manage the DNS configuration by generating or automatically +setting it depending on your registrar. + +- in the web interface via `Domains` > `{yourdomain.tld}` > `DNS`. +- with the command `yunohost domain dns suggest yourdomain.tld`. -YunoHost can generate a recommended DNS configuration for each domain, including the records required for e-mail. The recommended DNS configuration is available in the web administrator via Domains > (the domain) > DNS configuration, or with the command `yunohost domain dns suggest the.domain.tld`. +For automatic DNS configuration, check the [Registrars page](/admin/get_started/providers/registrar/). ## About Non-latin characters diff --git a/docs/admin/35.email/index.mdx b/docs/admin/35.email/index.mdx index 7cf3d7c7f0..33d2b7ca7b 100644 --- a/docs/admin/35.email/index.mdx +++ b/docs/admin/35.email/index.mdx @@ -17,7 +17,7 @@ To validate your setup: - if you are self-hosting at home and not using a VPN, ensure [your ISP won't block port 25](/admin/get_started/providers/isp/) ; - route ports according to [this documentation](/admin/get_started/post_install/port_forwarding) ; -- carefully configure mail DNS records according to [this documentation](/admin/get_started/post_install/dns_config) ; +- carefully configure mail DNS records according to [this documentation](/admin/domains/dns_configuration) ; - test your configuration using the diagnostic features ( → → Email ). You can also use [mail-tester.com](https://mail-tester.com), a score of at least 8~9/10 is a reasonnable goal (be careful : only 3 tests per domain per day are allowed) ## Email clients diff --git a/docs/admin/45.tutorials/05.domains/dns_dynamicip.mdx b/docs/admin/45.tutorials/05.domains/dns_dynamicip.mdx index 6b75c126c9..98d1cfc8b3 100644 --- a/docs/admin/45.tutorials/05.domains/dns_dynamicip.mdx +++ b/docs/admin/45.tutorials/05.domains/dns_dynamicip.mdx @@ -40,7 +40,7 @@ Register to one of them. It should provide you with one (or more) IP address to #### 2. Move the DNS zones -Copy the [DNS zones](/admin/get_started/post_install/dns_config), except for the NS fields, from the [registrar](#registrars) where you bought your domain name from to the dynamic DNS service you registrer at in step 1. +Copy the [DNS zones](/admin/domains/dns_configuration), except for the NS fields, from the [registrar](#registrars) where you bought your domain name from to the dynamic DNS service you registrer at in step 1. #### 3. Switch the management of your domain name to the dynamic DNS server @@ -48,7 +48,7 @@ This step consists in declaring to your [registrar](#registrars) that the DNS se For this, first declare in the NS field(s) the IP address provided by the DynDNS service. -Then, remove any other item in the [DNS zones](/admin/get_started/post_install/dns_config) (except the previous NS fields), from the [registrar](#registrars). +Then, remove any other item in the [DNS zones](/admin/domains/dns_configuration) (except the previous NS fields), from the [registrar](#registrars). #### 4. Configure the client diff --git a/docs/admin/45.tutorials/05.domains/dns_nohost_me.mdx b/docs/admin/45.tutorials/05.domains/dns_nohost_me.mdx deleted file mode 100644 index 25c30efce9..0000000000 --- a/docs/admin/45.tutorials/05.domains/dns_nohost_me.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Nohost.me domains ---- - -In order to make self-hosting as accessible as possible, the YunoHost Project provides a *free* and *automatically configured* domain name service. By using this service, you won't have to [configure DNS records](/admin/get_started/post_install/dns_config) yourself, which can be tedious and technical. - -The following (sub)domains are offered: - -- `whateveryouwant.nohost.me`; -- `whateveryouwant.noho.st`; -- `whateveryouwant.ynh.fr`. - -To use this service, you simply have to choose such a domain during the post-installation set up. It will then be automatically configured by YunoHost! - -:::tip -As a fairness measure, each instance may only have **one such domain** setup at any given time. -::: - -### Subdomains - -The `nohost.me`, `noho.st` and `ynh.fr` domain service allows the creation of subdomains. - -YunoHost allows the installation of applications on subdomains (for example, having the Nextcloud application accessible from the `cloud.mydomain.org` address), this feature is also allowed with the `nohost.me`, `noho.st` and `ynh.fr` domains and so it is possible to have a subdomain such as `my.application.mydomain.nohost.me`. To create a subdomain on `nohost.me`, `noho.st` and `ynh.fr`, you just have to add the subdomain to YunoHost like any other domains. - -### Adding a `nohost.me`, `noho.st` or `ynh.fr` domain after the post-installation - -If you already did the postinstall and want to add an automatic domain, you may do so from the "Domains" web interface, selecting the option "I don't have a domain name..." - -Alternatively, the following commands can be used. - -```bash -# Add the domain -yunohost domain add whateveryouwant.nohost.me - -# Subscribe/register to the dyndns service -yunohost dyndns subscribe -d whateveryouwant.nohost.me - -# [ wait ~ 30 seconds ] - -# Update the DNS conf -yunohost dyndns update - -# Set it as the main domain -yunohost domain main-domain -n whateveryouwant.nohost.me -``` - -### Retrieve a `nohost.me`, `noho.st` or `ynh.fr` domain - -If you reinstall your server and want to use a domain already used previously, you must request a domain reset on the forum [in the dedicated thread](https://forum.yunohost.org/t/nohost-domain-recovery/442). - -### Change a `nohost.me`, `noho.st` or `ynh.fr` domain - -If you wish to use a different automatic domain, you first have to remove your present domain registration. This is done in 3 steps: - -1. Remove the domain from your instance (via webadmin or the `yunohost domain remove` in the CLI). -2. Ask for registration removal [in the dedicated forum thread](https://forum.yunohost.org/t/nohost-domain-recovery/442). -3. Remove automatic domain configuration files on your server, via CLI only: `sudo rm /etc/cron.d/yunohost-dyndns && sudo rm -r /etc/yunohost/dyndns` - -You may then add a new domain. diff --git a/docs/admin/45.tutorials/05.domains/dns_subdomains.mdx b/docs/admin/45.tutorials/05.domains/dns_subdomains.mdx deleted file mode 100644 index ecbe480b74..0000000000 --- a/docs/admin/45.tutorials/05.domains/dns_subdomains.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: DNS and subdomains for the applications ---- - -### Subdomains - -YunoHost allows the use of subdomains. If one owns a domain name `mydomain.com`, one first needs to create the subdomains in the DNS configuration (with one's registrar like Gandi). - -### Configuration example with Gandi - -The DNS configuration needs an A record with an IPv4 address, an AAAA record with an IPv6 address, and various CNAME records, one for each desired subdomain. - -If your DNS configuration looks like: - -```text -@ A XYZ.XYZ.XYZ.XYZ -@ AAAA 1234:1234:1234:FFAA:FFAA:FFAA:FFAA:AAFF -* CNAME mydomain.com. -agenda CNAME mydomain.com. -blog CNAME mydomain.com. -rss CNAME mydomain.com. -``` - -then you can access `agenda.mydomain.com`, `blog.mydomain.com` and `rss.mydomain.com` subdomains. - -### Install an application on a subdomain - -To install an application on a subdomain in YunoHost, for example `blog.mydomain.com`, the configuration is done in the administration panel. One first add the subdomain to the available domains list. The creation of a subdomain in YunoHost will create the corresponding configuration files for NGINX (the web server used in YunoHost). - -Then, in the applications>install panel, one follows the classic installation process by choosing the desired subdomain as domain (for example `blog.mydomain.com`). One needs to choose the path `/` (in place of `/wordpress` for example). A warning message will appear telling that it won't be possible to install other application to this subdomain. After validation, the installation starts. - -The application is then available at `blog.mydomain.com` (and not `mydomain.com/wordpress`). - -### Moving an application to a subdomain - -What happens if the application is already installed? For example, one wants to move `mydomain.com/wordpress` to `blog.mydomain.com`. -It depends on the application. -Some applications allow the change of domain. In that case, one can proceed to the change through the administration panel: Applications > the_app_name > change URL. -If the application doesn't allow URL change, then there is no easy way to do it. The best solution is to reinstall the application. - -### Reinstalling an application - -First, save the application data through the backup process. Then uninstall the application with the administration panel. Then reinstall the application to the desired domain. Finally, restore the backup. diff --git a/docs/admin/50.troubleshooting/15.noaccess.mdx b/docs/admin/50.troubleshooting/15.noaccess.mdx index 8c00e18b73..b213ad78af 100644 --- a/docs/admin/50.troubleshooting/15.noaccess.mdx +++ b/docs/admin/50.troubleshooting/15.noaccess.mdx @@ -21,7 +21,7 @@ Check that you are getting access to the server by using its public IP (you can 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 have to configure your [DNS records](/admin/domains/dns_configuration) (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). diff --git a/docs/admin/50.troubleshooting/20.ipv6.mdx b/docs/admin/50.troubleshooting/20.ipv6.mdx index e143511867..88a8cabd2d 100644 --- a/docs/admin/50.troubleshooting/20.ipv6.mdx +++ b/docs/admin/50.troubleshooting/20.ipv6.mdx @@ -11,7 +11,7 @@ Please check [The OVH documentation](https://docs.ovh.com/gb/en/vps/configuring- ### Configure the DNS server -Also check [the documentation for subdomains](/admin/tutorials/domains/dns_subdomains). +Also check [the documentation for subdomains](/admin/domains/dns_configuration). ### Configure the server diff --git a/docusaurus.config.ts b/docusaurus.config.ts index e1e2ee869a..5117a2bd96 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -117,6 +117,7 @@ const config: Config = { theme: prismThemes.github, darkTheme: prismThemes.dracula, additionalLanguages: [ + 'autohotkey', 'bash', 'c', 'css', diff --git a/redirects.ts b/redirects.ts index 2b9912686e..a36eb950ec 100644 --- a/redirects.ts +++ b/redirects.ts @@ -10,6 +10,8 @@ const redirects_from_grav: Array<{ from: string; to: string }> = [ { from: '/ssh', to: '/admin/command_line', }, { from: '/domains', to: '/admin/domains/', }, { from: '/certificate', to: '/admin/domains/certificate', }, + { from: '/dns_nohost_me', to: '/admin/domains/dns_nohost_me', }, + { from: '/dns_subdomains', to: '/admin/domains/dns_configuration', }, { from: '/email', to: '/admin/email', }, { from: '/email_configure_client', to: '/admin/email/clients', }, { from: '/email_migration', to: '/admin/email/migration', }, @@ -38,8 +40,6 @@ const redirects_from_grav: Array<{ from: string; to: string }> = [ { from: '/certificate_custom', to: '/admin/tutorials/certificate_custom', }, { from: '/dns_dynamicip', to: '/admin/tutorials/domains/dns_dynamicip', }, { from: '/dns_local_network', to: '/admin/tutorials/domains/dns_local_network', }, - { from: '/dns_nohost_me', to: '/admin/tutorials/domains/dns_nohost_me', }, - { from: '/dns_subdomains', to: '/admin/tutorials/domains/dns_subdomains', }, { from: '/email_configure_relay', to: '/admin/tutorials/email_configure_relay', }, { from: '/external_storage', to: '/admin/tutorials/external_storage', }, { from: '/filezilla', to: '/admin/tutorials/filezilla', }, @@ -107,6 +107,9 @@ const redirects_from_grav: Array<{ from: string; to: string }> = [ { from: '/packaging_apps_helpers_v2.1', to: '/packaging/scripts/helpers_v2.1', }, { from: '/shell_variables_scope', to: '/packaging/scripts/shell_variables_scope', }, { from: '/packaging_testing', to: '/packaging/test', }, + + { from: '/admin/tutorials/domains/dns_nohost_me', to: '/admin/domains/dns_nohost_me', }, + { from: '/admin/tutorials/domains/dns_subdomains', to: '/admin/domains/dns_configuration', }, ]; const en_redirects_from_grav: Array<{ from: string; to: string }> = redirects_from_grav.map( diff --git a/static/img/webadmin/webadmin_domain.png b/static/img/webadmin/webadmin_domain.png index 0bb596203c..1d2fd1aa8e 100644 Binary files a/static/img/webadmin/webadmin_domain.png and b/static/img/webadmin/webadmin_domain.png differ diff --git a/static/img/webadmin/webadmin_domain_local.png b/static/img/webadmin/webadmin_domain_local.png index 4af8a73f1e..a128ac3608 100644 Binary files a/static/img/webadmin/webadmin_domain_local.png and b/static/img/webadmin/webadmin_domain_local.png differ diff --git a/static/img/webadmin/webadmin_domain_owndomain.png b/static/img/webadmin/webadmin_domain_owndomain.png index e3c4fe589a..8af42ace66 100644 Binary files a/static/img/webadmin/webadmin_domain_owndomain.png and b/static/img/webadmin/webadmin_domain_owndomain.png differ diff --git a/static/img/webadmin/webadmin_domain_remove_dyndns.png b/static/img/webadmin/webadmin_domain_remove_dyndns.png new file mode 100644 index 0000000000..40b5e25791 Binary files /dev/null and b/static/img/webadmin/webadmin_domain_remove_dyndns.png differ diff --git a/static/img/webadmin/webadmin_domain_subdomain.png b/static/img/webadmin/webadmin_domain_subdomain.png new file mode 100644 index 0000000000..895e292cf2 Binary files /dev/null and b/static/img/webadmin/webadmin_domain_subdomain.png differ diff --git a/static/img/webadmin/webadmin_dyndns.png b/static/img/webadmin/webadmin_dyndns.png index 059ae24c38..725b7a31e0 100644 Binary files a/static/img/webadmin/webadmin_dyndns.png and b/static/img/webadmin/webadmin_dyndns.png differ