# [`nfsn-utils`][] Interact with [NearlyFreeSpeech.NET][]'s [API][] from the command line. [`nfsn-utils`]: https://git.rcrnstn.net/rcrnstn/nfsn-utils [NearlyFreeSpeech.NET]: https://www.nearlyfreespeech.net [API]: https://en.wikipedia.org/wiki/API ## Goals `nfsn-utils` has three main goals: 1. **Be portable** (even to things like [routers][]). POSIX shell is used as glue for standard utilities. See [dependencies](#dependencies). 2. **Be modular** where it makes sense. [`nfsn-send`](#nfsn-send) is a general purpose [NearlyFreeSpeech.NET][] [API][] wrapper. [`nfsn-dns-update`](#nfsn-dns-update) is a general purpose [NearlyFreeSpeech.NET][] DNS update utility. 3. **Be opinionated with sane defaults** where it makes sense. The smaller utilities assume things like that you want to use [standard email addresses][]. 4. **Be easily auditable**. The scripts are well abstracted and no more than about 100 lines of code. [routers]: https://openwrt.org [standard email addresses]: https://www.ietf.org/rfc/rfc2142.txt ## Prerequisites ### API key As described in the [NearlyFreeSpeech.NET][] [documentation][], one needs to submit a [free assistance request][] to obtain an API key. Place the credentials in the environment variables `NFSN_LOGIN` and `NFSN_API_KEY` or in the file `./.nfsn-api` or `$HOME/.nfsn-api` (location overridable by the `NFSN_CREDENTIALS_PATH` environment variable). This file should be a JSON file consisting of an object with the keys `login` and `api-key`. (The file format and default location is compatible with [WebService::NFSN][] and [python-nfsn][].) [documentation]: https://members.nearlyfreespeech.net/wiki/API/Introduction [free assistance request]: https://members.nearlyfreespeech.net/support/assist?tag=apikey [WebService::NFSN]: https://metacpan.org/pod/WebService::NFSN#INTERFACE [python-nfsn]: https://github.com/ktdreyer/python-nfsn#authentication ### Dependencies - Unix-like environment (in particular, `/dev/urandom`). - [POSIX utilities][] with `date` supporting `+%s` (such as GNU `date`). - `sha1sum` (for instance, the one in `coreutils`). - [curl][]. - [jq][]. - `certbot` (only needed for `nfsn-dns-certbot*`). [POSIX utilities]: http://pubs.opengroup.org/onlinepubs/9699919799/idx/utilities.html [curl]: https://curl.haxx.se [jq]: https://github.com/stedolan/jq ## Included programs Dependency graph:  ### `nfsn-send` Wraps the Requests, Responses and Authentication described in the [NearlyFreeSpeech.NET][] [documentation][]. ### `nfsn-dns-update` Updates several DNS records and outputs what data was actually changed. ### `nfsn-dns-a` Updates DNS [A][] records, used to map hostnames to an IPv4 address. [A]: https://en.wikipedia.org/wiki/List_of_DNS_record_types#A ### `nfsn-dns-spf` Updates DNS [SPF][] records, used for email authorization (specifying who is allowed to send mail from a domain). [SPF]: https://en.wikipedia.org/wiki/Sender_Policy_Framework ### `nfsn-dns-dkim` Updates DNS [DKIM][] records, used for email authentication (using digital signatures). [DKIM]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail ### `nfsn-dns-dmarc` Updates DNS [DMARC][] records, extending [SPF][] and [DKIM][] by specifying failure policy and reporting. See also the [dmarc.org FAQ][]. [DMARC]: https://en.wikipedia.org/wiki/DMARC [dmarc.org FAQ]: https://dmarc.org/wiki/FAQ#Sender_Questions ### `nfsn-dns-certbot*` `nfsn-dns-certbot` calls [certbot][] (the [Electronic Frontier Foundation][]'s (EFF) [Let's Encrypt][] client, for getting HTTPS certificates) in [manual mode][] to make it use `nfsn-utils` to update DNS records in order to fullfill the [`dns-01` challenge][]. It does this by registering `nfsn-dns-certbot-{auth,cleanup}` as [hooks][]. By default, the `auth` hook sleeps for 30 seconds to let the DNS records propagate. This can be overridden with the environment variable `NFSN_DNS_CERTBOT_AUTH_SLEEP`. Given that `nfsn-dns-certbot` has successfully run once, running `certbot renew` will suffice to renew the certificates. [certbot]: https://certbot.eff.org [Electronic Frontier Foundation]: https://www.eff.org [Let's Encrypt]: https://letsencrypt.org [manual mode]: https://certbot.eff.org/docs/using.html#manual [`dns-01` challenge]: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.4 [hooks]: https://certbot.eff.org/docs/using.html#hooks ## License Licensed under the [ISC License][] unless otherwise noted, see the [`LICENSE`][] file. [ISC License]: https://choosealicense.com/licenses/isc [`LICENSE`]: LICENSE