327 lines
12 KiB
Plaintext
327 lines
12 KiB
Plaintext
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."
|
|
, expl' "Let's assume you have a web server and you host your website somewhere (A and AAAA records)."
|
|
, Bulma.p """
|
|
You want an A (IPv4) or AAAA (IPv6) record pointing to your server, named "enigma" for example.
|
|
"""
|
|
, expl' "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.
|
|
"""
|
|
, expl' "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 page 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 other 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: Domain-based Message Authentication Reporting and Conformance (DMARC).
|
|
"""
|
|
, 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.
|
|
"""
|
|
]
|
|
]
|
|
|
|
, Bulma.hr
|
|
, Bulma.h3 "How to automate the update of my IP address?"
|
|
, Bulma.p "Check out the \"Tokens? 🤨\" tab."
|
|
]
|
|
|
|
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 allows emails to be signed by the sender, and for the receiver to prove 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 allows 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 allows 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 from "
|
|
, HH.u_ [HH.text "your domain"]
|
|
, HH.text ". "
|
|
]
|
|
, HH.p []
|
|
[ HH.text """
|
|
This way, we can mitigate spam.
|
|
A server receiving a mail from your email address but coming from an IP address we 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 """
|
|
: default values should work great with simple domains.
|
|
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 with your email address but not from a listed domain or IP address?
|
|
"""
|
|
, HH.text """
|
|
By default, let's advise to drop the mail (a
|
|
"""
|
|
, HH.u_ [HH.text "hard fail"]
|
|
, HH.text """).
|
|
The only way for DKIM to be really meaningful is to block any mail not coming from the intended email servers.
|
|
Otherwise, it's just a statu quo, and the spamming will continue.
|
|
"""]
|
|
|
|
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."
|
|
]
|
|
]
|