479 lines
18 KiB
Text
479 lines
18 KiB
Text
module App.Text.Explanations where
|
|
import Halogen.HTML as HH
|
|
import Halogen.HTML.Properties as HP
|
|
import Bulma as Bulma
|
|
|
|
expl' :: forall w i. String -> HH.HTML w i
|
|
expl' text = expl [Bulma.p text]
|
|
expl :: forall w i. Array (HH.HTML w i) -> HH.HTML w i
|
|
expl content = Bulma.div_content [] [ Bulma.explanation content ]
|
|
expl_txt :: forall w i. String -> HH.HTML w i
|
|
expl_txt content = Bulma.explanation [ Bulma.p content ]
|
|
|
|
col :: forall w i. Array (HH.HTML w i) -> HH.HTML w i
|
|
col arr = Bulma.column_ [ Bulma.box arr ]
|
|
|
|
tokens :: forall w i. HH.HTML w i
|
|
tokens = HH.div_
|
|
[ Bulma.h3 "What are tokens?"
|
|
, expl' """
|
|
Tokens are a simple way to update a resource record (A or AAAA) with your current IP address.
|
|
"""
|
|
, HH.p_ [ HH.text "Let's take an example: you have an A record (IPv4) pointing to your web server at home, "
|
|
, HH.text "but your ISP changes your IP address from time to time. "
|
|
, HH.text "You can ask for a token (which looks like "
|
|
, HH.u_ [HH.text "53be0c45-61c4-4d29-8ae9-c2cc8767603d"]
|
|
, HH.text ") for this specific entry, then make your server regularly visit the following website."
|
|
]
|
|
, expl [ HH.p_ [ HH.text "https://beta.netlib.re/token-update/"
|
|
, HH.u_ [HH.text "<your-token>"]
|
|
]
|
|
]
|
|
, Bulma.p "For example: https://beta.netlib.re/token-update/53be0c45-61c4-4d29-8ae9-c2cc8767603d"
|
|
, Bulma.hr
|
|
, Bulma.h3 "How to automate the update of my IP address?"
|
|
, Bulma.p "On Linux, you can make your computer access the update link with the following command."
|
|
, expl [ Bulma.strong "wget https://beta.netlib.re/token-update/<your-token>" ]
|
|
, Bulma.p """
|
|
No need for a more complex program. This works just fine.
|
|
And you can run this command every hour.
|
|
For example, in your crontab (Linux and Unix related):
|
|
"""
|
|
, expl [ Bulma.strong "0 * * * * wget <url>" ]
|
|
, Bulma.p """
|
|
Commands for other operating systems may differ, but you get the idea.
|
|
"""
|
|
, Bulma.hr
|
|
, Bulma.h3 "The obvious trap ⚠"
|
|
, Bulma.p """
|
|
Make sure to access the website using the related IP address.
|
|
To update an IPv6 address (AAAA), force your application to access the URL using an IPv6 address.
|
|
"""
|
|
, expl [ HH.p_ [ Bulma.strong "wget -6 <url>" ]
|
|
, HH.p_ [ HH.text "To force the use of an IPv6 address." ]
|
|
, HH.p_ [ Bulma.strong "wget -4 <url>" ]
|
|
, HH.p_ [ HH.text "To force the use of an IPv4 address." ]
|
|
]
|
|
]
|
|
|
|
basics :: forall w i. HH.HTML w i
|
|
basics = HH.div_
|
|
[ Bulma.h3 "Basics of DNS"
|
|
, Bulma.p """
|
|
The domain name system (DNS) enables people share a name instead of an address to find a website or service.
|
|
"""
|
|
, Bulma.p """
|
|
To configure a zone, the first steps are trivial.
|
|
"""
|
|
|
|
, Bulma.hr
|
|
, Bulma.h3 "I have something to host (A and AAAA records)."
|
|
, expl' "Let's assume you have a web server and you host your website somewhere."
|
|
, Bulma.p """
|
|
You want an A (IPv4) or AAAA (IPv6) record pointing to your server, named "enigma" for example.
|
|
"""
|
|
|
|
, Bulma.hr
|
|
, Bulma.h3 "You need other names pointing to your server (CNAME records)."
|
|
, Bulma.p """
|
|
You may not want to use the name of your server "enigma" directly.
|
|
Instead, you may want the usual names for your services, such as "www" or "blog".
|
|
CNAME records are basically aliases, exactly to that end.
|
|
"""
|
|
|
|
, Bulma.hr
|
|
, Bulma.h3 "If you have other servers, just add more A or AAAA records."
|
|
, Bulma.p """
|
|
Tip: choose relevant names for your servers then add CNAME records.
|
|
For example, you can have an A record named "server1" and a CNAME "www" pointing to it.
|
|
The service isn't pointing to an actual IP address directly,
|
|
but to the name of the physical server providing the service.
|
|
You don't need to remember the IP address of each of your servers.
|
|
"""
|
|
|
|
, Bulma.hr
|
|
, Bulma.h3 "I want an email server."
|
|
, expl' """
|
|
Hosting a mail server is quite complex.
|
|
This section will focus on the main parts regarding the DNS.
|
|
"""
|
|
, Bulma.notification_danger' """
|
|
The actual configuration of your mail server is complex and depends on your choice of software.
|
|
This won't be covered here.
|
|
"""
|
|
, Bulma.p """
|
|
You need an MX record pointing to your "www" A (or AAAA) record.
|
|
"""
|
|
, Bulma.p """
|
|
Having an MX record isn't enough to handle a mail server.
|
|
You need to use a few spam mitigation mechanisms.
|
|
"""
|
|
, Bulma.columns_
|
|
[ col
|
|
[ expl' """
|
|
Spam mitigation 1: tell what are the right mail servers for your domain with Sender Policy Framework (SPF).
|
|
"""
|
|
, expl_txt """
|
|
You need a SPF record to tell other mail servers what are the acceptable mail servers for your domain.
|
|
"""
|
|
]
|
|
, col
|
|
[ expl' """
|
|
Spam mitigation 2: prove that the mails come from your mail server with DomainKeys Identified Mail (DKIM).
|
|
"""
|
|
, expl_txt """
|
|
You will have to configure your mail server to sign the emails you send.
|
|
This involves creating a pair of keys (public and private).
|
|
Your mail server will sign the mails with the private key,
|
|
and recipient mail servers will verify the signature with the public key.
|
|
So, you need to publish the public key in a DKIM record.
|
|
"""
|
|
]
|
|
, col
|
|
[ expl' """
|
|
Spam mitigation 3: mitigate fraud (impersonators) with Domain-based Message Authentication Reporting and Conformance (DMARC).
|
|
Tell other mail servers to only accept emails from your domain which actually are coming from your domain (SPF) and sent by your mail server (DKIM).
|
|
"""
|
|
, expl_txt """
|
|
Last but not least, DMARC.
|
|
"""
|
|
, Bulma.hr
|
|
, Bulma.p """
|
|
DMARC enables to check the "From:" field of a mail, based on the SPF and DKIM mechanisms.
|
|
Thus, domains with a DMARC record enable to only allow verified mails.
|
|
Valid emails come from an authorized IP address (SPF), are signed by the verified email server (DKIM) and have an email address coming from a verified domain (DMARC) related to the two previous spam mitigation mechanisms.
|
|
"""
|
|
, Bulma.hr
|
|
, Bulma.p """
|
|
With DMARC, you won't accept an email from "hacker@example.com" because it was sent by another domain with a valid SPF and DKIM.
|
|
"""
|
|
]
|
|
]
|
|
|
|
, Bulma.hr
|
|
, Bulma.h3 "How to automate the update of my IP address?"
|
|
, Bulma.p "Check out the \"Tokens? 🤨\" tab."
|
|
]
|
|
|
|
a_introduction :: forall w i. Array (HH.HTML w i)
|
|
a_introduction =
|
|
[ Bulma.p """
|
|
The A record enables to bind an IPv4 address to a domain.
|
|
"""
|
|
, HH.p []
|
|
[ HH.text "🚨 "
|
|
, HH.u_ [HH.text "Advice for beginners"]
|
|
, HH.text ":"
|
|
, HH.text """
|
|
the "Name" field is for the name of the record, which should be the name of the server owning this IP address, such as "server1".
|
|
The "Target" field is for the IP address.
|
|
The default TTL should be fine.
|
|
"""
|
|
]
|
|
]
|
|
|
|
aaaa_introduction :: forall w i. Array (HH.HTML w i)
|
|
aaaa_introduction =
|
|
[ Bulma.p """
|
|
The AAAA record enables to bind an IPv6 address to a domain.
|
|
"""
|
|
, HH.p []
|
|
[ HH.text "🚨 "
|
|
, HH.u_ [HH.text "Advice for beginners"]
|
|
, HH.text ":"
|
|
, HH.text """
|
|
the "Name" field is for the name of the record, which should be the name of the server owning this IP address, such as "server1".
|
|
The "Target" field is for the IP address.
|
|
The default TTL should be fine.
|
|
"""
|
|
]
|
|
]
|
|
|
|
cname_introduction :: forall w i. Array (HH.HTML w i)
|
|
cname_introduction =
|
|
[ Bulma.p """
|
|
The CNAME record enables to provide alternative names to records.
|
|
"""
|
|
, HH.p []
|
|
[ HH.text "🚨 "
|
|
, HH.u_ [HH.text "Advice for beginners"]
|
|
, HH.text ":"
|
|
, HH.text """
|
|
this resource record helps keeping your zone clean.
|
|
Let's say you have a server named "server1", you can register an A record for that server (since the server actually has an IP address).
|
|
Then, your hosted services will be registered in your zone as CNAMEs: "www", "blog" and "voip" will point to "server1", the actual server hosting these services.
|
|
"""
|
|
]
|
|
]
|
|
|
|
mx_introduction :: forall w i. Array (HH.HTML w i)
|
|
mx_introduction =
|
|
[ Bulma.p """
|
|
The MX record enables to add a mail server to your zone.
|
|
"""
|
|
, HH.p []
|
|
[ HH.text "🚨 "
|
|
, HH.u_ [HH.text "Advice for beginners"]
|
|
, HH.text ": handling a mail server is both complex and difficult."
|
|
, HH.text """
|
|
The tab "The basics 🧠" explains some parts of hosting a mail server, but keep in mind that this is time consuming to get it together.
|
|
This page talks about the DNS aspect of it, but doesn't cover all you need to know to actually host a mail server, by a long shot.
|
|
"""
|
|
]
|
|
, Bulma.p """
|
|
Anyway, the MX record itself is simple to understand.
|
|
Let's say you have a server named "server1" with your mail service.
|
|
The MX record can be named "mail" and it will target "server1".
|
|
Of course, "server1" needs a record for its IP address (A or AAAA).
|
|
"""
|
|
, Bulma.p """
|
|
The priority field is important only in case you have multiple mail servers; keep the default value.
|
|
"""
|
|
]
|
|
|
|
txt_introduction :: forall w i. Array (HH.HTML w i)
|
|
txt_introduction =
|
|
[ Bulma.p """
|
|
The TXT record enables to declare a small text.
|
|
"""
|
|
, HH.p []
|
|
[ HH.text "🚨 "
|
|
, HH.u_ [HH.text "Advice for beginners"]
|
|
, HH.text ":"
|
|
, HH.text """
|
|
do not use this record directly.
|
|
TXT records are used in several places, for example for mail security through SPF, DKIM and DMARC records.
|
|
"""
|
|
]
|
|
, Bulma.notification_danger' """
|
|
All of these specific records have a dedicated user interface on this website;
|
|
use them instead of writing these records by yourself.
|
|
"""
|
|
]
|
|
|
|
ns_introduction :: forall w i. Array (HH.HTML w i)
|
|
ns_introduction =
|
|
[ Bulma.p """
|
|
The NS record enables to declare a new Name Server, meaning a new server that would serve this zone.
|
|
"""
|
|
, Bulma.notification_danger' "🚨 Advice for beginners: do not use this resource record."
|
|
]
|
|
|
|
caa_introduction :: forall w i. Array (HH.HTML w i)
|
|
caa_introduction =
|
|
[ Bulma.p """
|
|
The CAA record enables to specify a certification authority that is authorized to issue certificates for the domain.
|
|
The idea is to reduce the risk of unintended certificate mis-issue.
|
|
"""
|
|
, Bulma.p """
|
|
Certification authorities (CA) may issue certificates for any domain.
|
|
Thus, any CA may provide certificates for a domain (let's say google.com) to any hacker that can now impersonate the domain.
|
|
The CAA record allows to say what is the authorized CA for the domain, preventing this kind of attacks.
|
|
"""
|
|
-- , HH.p []
|
|
-- [ HH.text "🚨 "
|
|
-- , HH.u_ [HH.text "Advice for beginners"]
|
|
-- , HH.text ":"
|
|
-- , HH.text """
|
|
-- """
|
|
-- ]
|
|
]
|
|
|
|
dkim_introduction :: forall w i. Array (HH.HTML w i)
|
|
dkim_introduction =
|
|
[ Bulma.p """
|
|
DKIM is a way to share a public signature key for the domain.
|
|
This enables emails to be signed by the sender and for the receiver to verify the origin of the mail.
|
|
"""
|
|
, HH.p []
|
|
[ HH.text """
|
|
Default name is fine, change it only if you know what you are doing.
|
|
For the configuration of your mail server, remember that your
|
|
"""
|
|
, HH.u_ [HH.text "selector"]
|
|
, HH.text " is "
|
|
, Bulma.strong "default"
|
|
, HH.text "."
|
|
]
|
|
]
|
|
|
|
dmarc_introduction :: forall w i. Array (HH.HTML w i)
|
|
dmarc_introduction =
|
|
[ Bulma.p """
|
|
DMARC is a spam mitigation mechanism on top of SPF and DKIM.
|
|
Upon receiving a mail, the server checks whether the "From:" field of the mail is consistent with the SPF and DKIM
|
|
records of the sender's domain.
|
|
The DMARC record tells what to do with the mail in case of an inconsistency, and DMARC enables to define email
|
|
addresses that should receive error reports.
|
|
"""
|
|
]
|
|
|
|
dmarc_policy :: forall w i. Array (HH.HTML w i)
|
|
dmarc_policy =
|
|
[ Bulma.p """
|
|
DMARC record enables to tell receivers what to do with a non-conforming message;
|
|
a message that wasn't properly secured with SPF and DKIM.
|
|
"""
|
|
, Bulma.p """
|
|
This message can either be accepted ("None") or rejected, or even quarantined, meaning to be considered as suspicious.
|
|
This can take different forms, such as being flagged, marked as spam or have a high "spam score", it's up to the receiver.
|
|
"""
|
|
]
|
|
|
|
dmarc_sp_policy :: forall w i. Array (HH.HTML w i)
|
|
dmarc_sp_policy =
|
|
[ Bulma.p """
|
|
Same as the previous entry, but for sub-domains.
|
|
"""
|
|
]
|
|
|
|
dmarc_adkim :: forall w i. Array (HH.HTML w i)
|
|
dmarc_adkim =
|
|
[ Bulma.p """
|
|
Consistency policy for DKIM. Tell what should be considered acceptable.
|
|
"""
|
|
, Bulma.p """
|
|
This is about the relation between the email "From:" field and the domain field of the DKIM signature ("d:").
|
|
"""
|
|
, Bulma.p """
|
|
The policy can be either strict (both should be identical) or relaxed (both in the same Organizational Domain).
|
|
"""
|
|
]
|
|
|
|
dmarc_aspf :: forall w i. Array (HH.HTML w i)
|
|
dmarc_aspf =
|
|
[ Bulma.p """
|
|
Consistency policy for SPF. Tell what should be considered acceptable.
|
|
"""
|
|
, Bulma.p """
|
|
First, SPF should produce a passing result.
|
|
Then, the "From:" and the "MailFrom:" fields of the received email are checked.
|
|
"""
|
|
, Bulma.p """
|
|
In strict mode, both fields should be identical.
|
|
In relaxed mode, they can be different, but in the same Organizational Domain.
|
|
"""
|
|
, Bulma.p """
|
|
From RFC7489: For example, if a message passes an SPF check with an
|
|
RFC5321.MailFrom domain of "cbg.bounces.example.com", and the address
|
|
portion of the RFC5322.From field contains "payments@example.com",
|
|
the Authenticated RFC5321.MailFrom domain identifier and the
|
|
RFC5322.From domain are considered to be "in alignment" in relaxed
|
|
mode, but not in strict mode.
|
|
"""
|
|
, HH.p_
|
|
[ HH.text "See "
|
|
, HH.a [HP.href "https://publicsuffix.org/"] [ HH.text "publicsuffix.org" ]
|
|
, HH.text " for a list of organizational domains."
|
|
]
|
|
]
|
|
|
|
dmarc_contact :: forall w i. Array (HH.HTML w i)
|
|
dmarc_contact =
|
|
[ Bulma.p """
|
|
In case you want to receive error reports, enter email addresses that should receive either an aggregated report or a detailed report of the occurring errors.
|
|
"""
|
|
]
|
|
|
|
dmarc_ri :: forall w i. Array (HH.HTML w i)
|
|
dmarc_ri =
|
|
[ Bulma.p """
|
|
Requested report interval. Default is 86400.
|
|
"""
|
|
]
|
|
|
|
dmarc_pct :: forall w i. Array (HH.HTML w i)
|
|
dmarc_pct =
|
|
[ Bulma.p """
|
|
Sampling rate.
|
|
Percentage of messages subjected to the requested policy.
|
|
"""
|
|
]
|
|
|
|
|
|
dkim_default_algorithms :: forall w i. Array (HH.HTML w i)
|
|
dkim_default_algorithms =
|
|
[ Bulma.p """
|
|
Default values should be fine (RSA + SHA256), change them only if you know what you are doing.
|
|
Just enter your public key.
|
|
"""
|
|
]
|
|
|
|
spf_introduction :: forall w i. Array (HH.HTML w i)
|
|
spf_introduction =
|
|
[ HH.p []
|
|
[ HH.text "Sender Policy Framework (SPF) is a way to tell the "
|
|
, HH.u_ [HH.text "other mail servers"]
|
|
, HH.text " which are the mail servers supposed to send mails with email addresses from "
|
|
, HH.u_ [HH.text "your domain"]
|
|
, HH.text ". "
|
|
]
|
|
, HH.p []
|
|
[ HH.text """
|
|
This way, you can mitigate spam.
|
|
A server receiving a mail from your email address but coming from an IP address you didn't list as authorized will be discarded.
|
|
This is not a bullet-proof technique, but it's simple enough and works great with the most basic forms of spam.
|
|
"""
|
|
]
|
|
, HH.p []
|
|
[ HH.text "A correctly configured domain with a mail server should only advertise the right IP addresses that can possibly send mails from the domain."
|
|
]
|
|
, HH.p []
|
|
[ HH.u_ [HH.text "Advice for beginners"]
|
|
, HH.text ":"
|
|
, HH.text """
|
|
default values should work great with simple domains.
|
|
Don't change anything, just click on the "Add" button below.
|
|
In addition, make sure to have an MX record, which should be pointing to an A or AAAA record, and that will do it. 🥳
|
|
"""
|
|
]
|
|
]
|
|
|
|
spf_default_behavior :: forall w i. Array (HH.HTML w i)
|
|
spf_default_behavior = [
|
|
Bulma.p """
|
|
What should someone do when receiving a mail from your email address but not from a listed domain or IP address?
|
|
"""
|
|
, HH.p_ [ HH.text """
|
|
By default, the mail is dropped (a
|
|
"""
|
|
, HH.u_ [HH.text "hard fail"]
|
|
, HH.text """).
|
|
This is the most direct behavior: dropping any mail not coming from the intended email servers.
|
|
"""
|
|
]
|
|
, HH.p_ [ HH.text """
|
|
Another option would be a
|
|
"""
|
|
, HH.u_ [HH.text "soft fail"]
|
|
, HH.text """, which would advise recipient mail servers to tag the mails as spam.
|
|
In this case, a misconfigured email server wouldn't prevent mails to be received.
|
|
Use this option in case you are not confident enough in your setup.
|
|
"""
|
|
]
|
|
, HH.p_ [ HH.text """
|
|
Other options ("pass" and "neutral") are frankly borderline useless.
|
|
Do not use them unless you know exactly why.
|
|
"""
|
|
]
|
|
]
|
|
|
|
srv_introduction :: forall w i. Array (HH.HTML w i)
|
|
srv_introduction =
|
|
[ Bulma.p "The SRV record is a DNS resource record for specifying the location of services."
|
|
, HH.p_ [ HH.text "Given a specific "
|
|
, HH.u_ [HH.text "service name"]
|
|
, HH.text " (which may be arbitrary) and a "
|
|
, HH.u_ [HH.text "protocol"]
|
|
, HH.text " (such as TCP or UDP), you can tell where the server is (address name and port). "
|
|
, HH.text """
|
|
Both the names of the service and the protocol are used to construct the name of the resource record.
|
|
"""
|
|
]
|
|
, HH.p_ [ HH.text "For example, for a service named "
|
|
, HH.u_ [HH.text "voip"]
|
|
, HH.text " and given that this service uses the TCP protocol, the target "
|
|
, HH.u_ [HH.text "\"server1.example.com.\""]
|
|
, HH.text " could be specified."
|
|
]
|
|
]
|