DUCK(1)

🦋 NAME 🦋

okay so bestie, let me introduce you to duck — the Debian Url ChecKer. yes, that acronym is a whole stretch and we love that for it 💅

---

✨ SYNOPSIS ✨

duck [ OPTION ]... [-f file] [-u file] [-c file] [URL]

---

🌸 DESCRIPTION 🌸

okay so duck goes on a lil scavenger hunt and extracts links, email address domains and VCS-* entries out of all these files:

• debian/control
• debian/upstream, debian/upstream-metadata.yaml and debian/upstream/metadata
• debian/copyright
• DEP-3 patch files in every directory a series file is found
• systemd.unit files (*.socket, *.device, *.mount, *.automount, *.swap, *.target, *.path, *.time, *.snapshot, *.slice, *.scope)
• Appstream files (*.appdata)

and if you hand it a URL? bestie it's not even gonna look at your current directory — it whips out dget to download that URL and processes the downloaded source package (the *.dsc file) instead 🫶

then it literally goes and tries to access those VCS-* entries and URLs using the appropriate tool to figure out if each one is broken or working. and if errors get detected? it shows you the filename, fieldname and URL/email of the broken entry. no guessing games, it tells you exactly which one is giving nothing 💀

here's the chill part: duck searches for the default files (all listed above) and just skips them silently if they're not there. but — and this is the plot twist — if you give it specific filenames for the options -c, -f or -u, and one of those files can't be found, duck exits with exit code 2. it's not playing about your custom paths, periodt.

Email address domains get checked for existing MX records, A records, or AAAA records, in that exact order. if none of those 3 show up for a given domain, it's considered broken. sorry to that domain 🙈

the 3 error levels 💅

Checks results are displayed with 3 different error levels:

• O: — (OK) the check didn't result in an error. only shown if -n is used.
• I: — (Information) informational warnings, suchs as missing helper tools, plus failing checks based on searches in unstructured text files, which sometimes lead to false positives.
• E: — (Error) failing checks based on data from well-defined fields (e.g. Homepage: entry in debian/control).

and the 3 certainty levels 👑

• certain — data taken from well defined fields. since the format of that field is specified (e.g. Debian Policy, etc.), it can be checked by the appropriate tools. if the check then fails, the data in the field is certainly erroneous.
• possible — data extracted using regular expressions (e.g. email addresses, URLs). this might lead to false positives, so the check result is possibly a false positive.
• wild-guess — data extracted from websites, by using regular expressions. this is still experimental and probably buggy, hence the "wild-guess". it's giving chaos, honestly.

---

🎀 OPTIONS 🎀

• -n — dry run. doesn't run any checks, just shows you the entries that would be checked.
• -q — quiet mode. suppresses all output.
• -v — verbose mode. shows all URLs found and the checks run. the yapper mode, we stan.
• --modules-dir=DIRECTORY — specify the modules directory. mostly useful for developing new checks. if this parameter is specified, only modules defined in this directory are used. you have to copy all *.pm files from /usr/share/duck/lib/checks to the directory specified.
• --color=[WHEN] — specify when to emit escape sequences to the output. available options are:
  • auto — emit color escape codes on STDOUT/STDERR, no color if output is piped to a file or the current terminal is not capable of displaying colors.
  • always — always emit color escape codes.
  • never — never emit color escape codes.
• --no-https — do not try to find matching https URLs to http URLs. see also the DUCK_NOHTTPS environment variable.
• --no-check-certificate — do not check if SSL certificates autenticity. this is highly discouraged! 🚨 bestie do NOT
• --missing-helpers — display list of missing external helper tools and exits.
• --version — display copyright and version information.
• -f — specify path to control file. this overrides the default debian/control.
• -F — skip processing of the control file.
• -u — specify path to upstream metadata file. this overrides the default files debian/upstream, debian/upstream-metadata.yaml and debian/upstream/metadata.
• -U — skip processing of the upstream metadata file.
• -c — specify path to copyright file. this overrides the default debian/copyright.
• -C — skip processing of copyright file.
• -P — skip processing of patch files.
• -A — skip processing of appstream metadata files.
• -S — skip processing of systemd.unit files.
• -l filename — process URLs, email addresses, git:// and svn:// entries from the file specified. specify one entry per line. this also disables all other check modules searching for entries in various files.
• --disable-urlfix=<fix1,...> — disables the specified url fix(es). an urlfix tries to remove leading/trailing characters from extracted URLs, like trailing dots or parentheses. using this parameter enables all urlfixes minus the specified ones.
• --enable-urlfix=<fix1,...> — enables the specified url fix(es). using this parameter disabled all urlfixes minus the specified ones.

The following urlfixes are available:

• TRAILING_COLON — removes trailing colon ":" character.
• TRAILING_PAREN_DOT — removes the string ")." from the end of the URL.
• TRAILING_PUNCTUATION — removes trailing "." and "," characters.
• TRAILING_QUOTES — removes trailing single quotes "'" characters. Note: double quotes (") are already correctly handled by the used perl regex matchers.
• TRAILING_SLASH_DOT — removes the string "/." (without the quotes) from the end of the URL.
• TRAILING_SLASH_PAREN — removes the string "/)" (without the quotes) from the end of the URL.

• --tasks=[number] — specify the number of checks allowed to run in parallel. default value is 24. this value must be an integer value >0.

All urlfixes are enabled by default. 💖

---

🌈 ENVIRONMENT VARIABLES 🌈

• DUCK_NOHTTPS — if this variable is set, do not try to find matching https URLs to http URLs.
• XDG_CONFIG_HOME — if this variable is set, use the config file (if any) $XDG_HOME/duck/duck.conf. the default value is $HOME/.config/duck/duck.conf .
• XDG_CONFIG_DIRS — defines the preference-ordered set of base directories to search for configuration files in addition to the XDG_CONFIG_HOME base directory. the directories in XDG_CONFIG_DIRS should be separated with a colon ':'.

---

🦋 EXAMPLE 🦋

to run duck, change your working directory to an extracted Debian source package and run:

duck

that's it. that's the whole thing. go off 👑

---

💀 EXIT STATUS 💀

• 0 — success, no errors 🌸
• 1 — error(s) detected 😭
• 2 — user-specified file not found 🙈

---

🍓 FILES 🍓

• debian/duck-overrides — overrides-file in the Debian package source tree. this files contains a list of URL regexs which should not be reported as down/broken. this might be useful in cases, where URLs are extracted from old/outdated copyright-files or patches, which will never ever be working, and which will then lead to false positives. please see an example in /usr/share/doc/duck/examples.
• duck.conf — config file which contains the regular expressions used to detect parked domains and redirected websites. the default file is in /etc/duck/duck.conf. duck also honors the XDG Base Directory Specification, see the section ENVIRONMENT VARIABLES for details. search order for duck.conf is:
  1. $XDG_CONFIG_HOME/duck/duck.conf (default: $HOME/.config/duck/duck.conf)
  2. /etc/duck/duck.conf
  3. /$XDG_CONFIG_DIRS (default: /etc/xdg/duck/duck.conf)

please see the XDG Base Directory Specification (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for more details.

---

👀 SEE ALSO 👀

please see http://duck.debian.net/ for additional information as well as an overview of duck checks run on all source packages in Debian/unstable. it's lowkey iconic, go look 🌟

---

and that's the whole page bestie 💖 this one's from the General Commands Manual, dated 2017-08-10, filed under DUCK(1) — no cap, that's the whole vibe check, now go check some URLs 🦋✨