{"id":15115105,"url":"https://github.com/samboy/MaraDNS","last_synced_at":"2025-09-27T20:31:49.625Z","repository":{"id":23425207,"uuid":"26788089","full_name":"samboy/MaraDNS","owner":"samboy","description":"MaraDNS: A small open-source DNS server","archived":false,"fork":false,"pushed_at":"2024-09-20T15:40:05.000Z","size":8860,"stargazers_count":512,"open_issues_count":1,"forks_count":65,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-09-27T01:47:17.828Z","etag":null,"topics":["dns","dns-servers","recursive-dns"],"latest_commit_sha":null,"homepage":"https://maradns.samiam.org/","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samboy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.TXT","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-11-18T02:23:49.000Z","updated_at":"2024-09-24T01:45:56.000Z","dependencies_parsed_at":"2023-10-15T03:43:24.529Z","dependency_job_id":"c29af47f-3c65-41ac-994e-beff41658efd","html_url":"https://github.com/samboy/MaraDNS","commit_stats":null,"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samboy%2FMaraDNS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samboy%2FMaraDNS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samboy%2FMaraDNS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samboy%2FMaraDNS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samboy","download_url":"https://codeload.github.com/samboy/MaraDNS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234460505,"owners_count":18836837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dns","dns-servers","recursive-dns"],"created_at":"2024-09-26T01:43:40.743Z","updated_at":"2025-09-27T20:31:48.413Z","avatar_url":"https://github.com/samboy.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# What is MaraDNS\n\nMaraDNS is a free open-source computer program written by Sam Trenholme.\n\nMaraDNS implements the Domain Name System (DNS), an essential internet\nservice. MaraDNS is open source software: This means that anyone is\nfree to download, use, and modify the program free of charge, as per\nits license. \n\nPeople like MaraDNS because it’s small, lightweight, easy to set up,\nand remarkably secure. It’s also cross platform — the program runs\nboth in Windows and in UNIX clones.\n\nMaraDNS has a web page and blog at https://maradns.samiam.org.\nMaraDNS’s Git tree is hosted at \n[GitHub](https://github.com/samboy/MaraDNS),\n[GitLab](https://gitlab.com/maradns/maradns), \n[Bitbucket](https://bitbucket.org/maradns/maradns/),\n[Codeberg](https://codeberg.org/samboy/MaraDNS),\nand \n[SourceHut](https://git.sr.ht/~samiam/MaraDNS)\n(Please use \n[GitHub discussions](https://github.com/samboy/MaraDNS/discussions) \nfor bug reports).  \n\n# ABOUT\n\nMaraDNS is a small and lightweight cross-platform open-source DNS\nserver. The server is remarkably easy to configure for someone\ncomfortable editing text configuration files. MaraDNS is released under\na BSD license.\n\nI initially wrote MaraDNS while I was a college student and a travelling\nEnglish teacher during the first 2000s decade.\n\nSince the COVID-19 pandemic, I have been actively adding new features\nto MaraDNS, most notably the new `coLunacyDNS` service which uses Lua\nto customize DNS replies.\n\nVersions of some MaraDNS programs compiled as Windows binaries\n(without needing Cygwin or another POSIX emulation library) are\nin the folder `maradns-win32/`\n\n# Building MaraDNS\n\nTo build MaraDNS, one needs a POSIX system with:\n\n* A POSIX compatible shell\n* A POSIX compatible implementation of `make`, which has the POSIX202X\n  feature of allowing a make target to have a `/` in it.\n* Other standard POSIX utilities (`awk`, etc.)\n* A current C compiler which can support, via `stdint`, 8-bit, 16-bit, \n  32-bit, and 64-bit sized integers.\n* A POSIX C library with both POSIX and Berkeley socket support.\n\n(To build some of the documentation, the non-standard but widely\n available `unix2dos` text conversion utility is used.)\n\nThen, do this:\n\n```\n./configure\nCC=cc # Change this to gcc/clang/tcc as desired\nexport CC\nmake\n```\n\nNote that most implementations of `make` will set `$CC` to `cc` if it’s\nnot already set, but the [POSIX spec](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html)\nsays that the default value should be `c99`, a compiler which will not\ncompile MaraDNS.  A POSIX program like MaraDNS will not compile with a\nstrictly ISO compliant C compiler (the POSIX system calls will fail to\ncompile).  However, all of the C programs here compile with `gcc`,\n`clang`, and `tcc`, and should compile with any reasonable POSIX C\ncompiler.\n\nAll of these are very standard tools which are included with the vast\nmajority of Linux and BSD distributions; packages usually have names like:\n\n* `clang` (which uses `llvm`) for the C compiler\n* `libc-dev` for the development C standard library, which will have sockets\n* `make` for make; if one does not wish to use GNU make (the Linux standard),\n  other make implementations exist, e.g. https://github.com/samboy/maramake\n* POSIX compatible implementations of `sh`, `awk`, and other utilities are\n  also almost always included as part of a Linux base install.\n\nMaraDNS successfully compiles with `gcc`, `clang`, and `tcc`; it \nsuccessfully builds with GNU make, bmake, pdpmake (as long as non-POSIX\nand/or POSIX202X extensions are enabled and `CC` has the value `cc`), and \nmaramake.  The version of `make` used to compile MaraDNS needs to have \nthe command name `make`.  MaraDNS compiles and runs with both Busybox \nversions of the core POSIX utilities and GNU coreutils.\n\n## Supported OSes\n\nMaraDNS is built and runs on Ubuntu 22.04 as of late 2022.  \n\nI currently use Ubuntu 22.04 to develop MaraDNS, both Ubuntu 22.04 and\nAlpine Linux 3.14 to test that MaraDNS builds and passes all automated\nregressions, and a Windows XP virtual machine to make the Windows\nbinaries.\n\n### Please use systemd\n\nWhile MaraDNS does have scripts for starting up MaraDNS at system boot\ntime on `sysvinit` systems, these scripts are no longer fully supported,\nsince most major Linux distributions have moved on to `systemd`, which\nis a lot better than the older `sysvinit` process for starting up the\nMaraDNS related services.\n\nWhile `make install` is only guaranteed to get MaraDNS to start up at\nsystem boot time on Ubuntu 22.04, it *should* do the right thing in Rocky\nLinux, Debian, RedHat, CentOS, Fedora, and other Linux distributions\nwhich use `systemd`.\n\nThere *is* some scaffolding for getting MaraDNS to run without `systemd`.\nThere is a helper, `duende`, to make MaraDNS a daemon on systems with\nclassic *NIX style init.  While, with `systemd`, it’s no longer needed\nto use this Duende helper, I will keep Duende around for `sysvinit` and\nsome level of `OpenRC` compatibility.  There are also shell scripts for\nstarting MaraDNS on `sysvinit` systems which may or may not work with\nother init systems.\n\n`systemd` handles the daemonization of the MaraDNS services the way\n`duende` does (did?) on `sysvinit` and similar systems.  The `systemd` way\nis much simpler at the development level, since systemd now handles a lot\nof complexity the old init systems forced networking services to handle.\n\n## Important note for Windows users\n\nUsers of Microsoft Windows are better off downloading a prebuilt Windows\nbinary: http://maradns.samiam.org/download.html (or, look in the\nfolder `maradns-win32` here) \nBe sure to download the file with the .zip extension.\n\nOnly Deadwood and coLunacyDNS binaries are provided.  \n\nDeadwood has passed Y2038 tests in Windows 10.\n\n# What is DNS\n\nThe internet uses numbers, not names, to find computers. DNS is the\ninternet’s directory service: It takes a name, like “www.maradns.org”,\nand converts that name in to an “IP” number that your computer can use\nto connect to www.maradns.org.\n\nDNS is one of these things many take for granted that is essential to\nusing today’s internet. Without DNS, the internet breaks. It is\ncritical that a DNS server keeps the internet working in a secure and\nstable manner.\n\n# MaraDNS' History\n\nMaraDNS was started in 2001 in response to concerns that there were\nonly two freely available DNS servers (BIND and DjbDNS) at the time.\nMaraDNS 1.0 was released in mid-2002, MaraDNS 1.2 was released in late\n2005, MaraDNS 2.0 was released in the fall of 2010, and MaraDNS had\na version number jump up to 3.3 in 2019 in order to have the same version \nnumber as Deadwood.\n\nMaraDNS 1.0 used a recursive DNS server that was implemented rather\nquickly and had difficult-to-maintain code. This code was completely\nrewritten for the MaraDNS 2.0 release, which now uses a separate\nrecursive DNS server.\n\n# Overview\n\nMaraDNS 3.5 consists of three primary components: A UDP-only authoritative\nDNS server for hosting domains, a UDP recursive DNS server called\n`Deadwood` for finding domains on the internet, and a Lua-powered DNS\nserver called `coLunacyDNS`. MaraDNS’ recursive DNS server `Deadwood`\nshares no code with MaraDNS’ authoritative DNS server.\n\n`coLunacyDNS` is a Lua-based name server which uses a combination of C\n(for the heavy lifting of binding to DNS sockets, processing DNS requests,\nand handling pending replies from upstream DNS servers) and Lua (for\ndeciding how to respond to a given query) to have both performance\nand flexibility.\n\nIn more detail: MaraDNS has one daemon, the authoritative daemon\n(called `maradns`), that provides information to recursive DNS servers\non the internet, and another daemon, the recursive daemon (called\n`Deadwood`), that gets DNS information from the internet for web\nbrowsers and other internet clients.\n\nA simplified way to look at it: `MaraDNS` puts your web page on the\nInternet; `Deadwood` looks for web pages on the Internet.\n\nSince MaraDNS’ authoritative daemon does not support TCP, MaraDNS\nincludes a separate DNS-over-TCP server called `zoneserver` that\nsupports both standard DNS-over-TCP and DNS zone transfers.\n\nNeither MaraDNS nor the UNIX version of Deadwood have support for\ndaemonization; this is handled by a separate program included with\nMaraDNS called `Duende`. Deadwood's Windows port, on the other hand,\nincludes support for running as a Windows service.\n\nMaraDNS also includes a simple DNS querying tool called `askmara` and\na number of other miscellaneous tools: Lua 5.1 scripts for processing\nMaraDNS' documentation (since MaraDNS comes with a fork of Lua 5.1, these\nscripts do not have an external dependency), some Unicode conversion\nutilities, scripts for building and installing MaraDNS, automated SQA\ntests, etc.\n\n`MaraDNS` is a native UNIX program which can run in Windows via cygwin.\nBoth `Deadwood`, MaraDNS' recursive resolver, and `coLunacyDNS`, a DNS\nserver configured with a Lua 5.1 script, are cross-platform applications\nwith full Windows ports.\n\nMaraDNS 2.0 has full (albeit not fully tested) IPv6 support.\n\n# Internals\n\nMaraDNS 3.5’s authoritative server uses code going all the way back \nto 2001. The core DNS-over-UDP server has a number of components,\nincluding two different zone file parsers, a mararc parser, a secure\nrandom number generator, and so on.\n\nMaraDNS is written entirely in C. No objective C nor C++ classes are\nused in MaraDNS’ code.\n\nMaraDNS 2.0’s “Deadwood” recursive server was started in 2007 and has\nfar cleaner code. Its random number generator, for example, uses a\nsmaller, simpler, and more secure cryptographic algorithm; its\nconfiguration file parser uses a finite state machine interpreter; its\nhandling of multiple simultaneous pending connections is done using\nselect() and a state machine instead of with threads.\n\n# Other DNS servers\n\nThe landscape of open-source DNS servers has changed greatly since 2001\nwhen MaraDNS was started. There are now a number of different DNS\nservers still actively developed and maintained: BIND, Power DNS,\nNSD/Unbound, as well as MaraDNS. DjbDNS is no longer being updated and\nthe unofficial forks have limited support; notably it took nearly five\nmonths for someone to come up with a patch for CVE-2012-1191.\n\nMaraDNS’ strength is that it’s a remarkably small, lightweight, easy to\nconfigure, and mostly cross-platform DNS server. Deadwood is a tiny DNS\nserver with full recursion support, perfect for embedded systems.\n\nMaraDNS’ weakness is that it does not have some features other DNS\nservers have. For example, while Deadwood has the strongest spoof\nprotection available without cryptography, it does not have support for\nDNSSEC.\n\nAs another example, MaraDNS does not have full zone transfer support;\nwhile MaraDNS can both serve zones and receive external zone files from\nother DNS servers, MaraDNS needs to be restarted to update its database\nof DNS records.\n\n# MaraDNS’ future\n\nMaraDNS is a mature application.  Being open source code, the amount\nof time I have to devote to MaraDNS is highly variable.  Right now,\nI am concentrating my efforts to revamp MaraDNS so that it can \ncontinue to compile and run for as long as possible, minimizing the\nnumber of external dependencies so that outside changes are unlikely\nto break MaraDNS.\n\nFor MaraDNS to break, either the C language would have to change to\nbreak programs that compile with few to no warnings here in the 2020s,\nor the POSIX standard would have to change to the point that POSIX\ncompliant scripts which run here in the 2020s no longer run.  Both\nof these are very unlikely to happen.\n\n## Y2038 statement\n\nMaraDNS is fully Y2038 compliant on systems with a 64-bit time_t.  Here\nin the 2020s, even 32-bit Linux distributions, such as Alpine Linux,\nhave a 64-bit time_t.\n\nDeadwood, in addition, for its Windows 32-bit binary, uses Windows\nfiletime to generate internal timestamps; filetime stamps will not run\nover until the year 30827 or so.  \n\ncoLunacyDNS, likewise, uses Windows filetime for timestamps with its\nWin32 binary.\n\nOn *NIX systems with a 32-bit `time_t`, some features which depend on \nOS-level time and date libraries are disabled.  MaraDNS has support for\nshowing a human readable timestamp with the `timestamp_type` parameter;\nthis parameter is disabled on systems with a 32-bit `time_t` since the\nunderlying libraries MaraDNS uses will probably fail at the Y2038 cutoff.\nLikewise, MaraDNS has support for generating a human-readable SOA\nserial number with the `synth_soa_serial` parameter, but this feature\nis disabled if `time_t` is 32-bit.  In both cases, the feature in\nquestion is, by default, disabled in MaraDNS, so only users who have\nexplicitly enabled these features will see any change in behavior.\n\nMaraDNS has the ability to generate a synthetic SOA serial number if\na zone file does not have a SOA record.  The SOA serial is based on the\ntimestamp for the zone file.  If `time_t` is 32-bit, MaraDNS assumes that\nthe `stat` call will return a negative timestamp after the Y2038 cutoff,\nand will adjust timestamps from before 2001 (the year MaraDNS was first\ndeveloped) to be after the Y2038 cutoff.  If there are systems out there\nwhere a `stat` call for a file’s modification time fail after the Y2038\ncutoff, one can avoid Y2038 issues by having a SOA record with a serial\nnumber in zone files.  The Windows port of MaraDNS, as of 3.5.0028,\nuses Windows Y2038 compliant system calls instead of POSIX calls to get\nzone file timestamps.\n\nBoth Deadwood and coLunacyDNS make some effort to generate accurate\ntimestamps on *NIX systems with a 32-bit time_t until later than\n2106; this code assumes that 32-bit systems will have the time\nstamp “wrap around” after 2038 but still have the 32-bit time be \nupdated.\n\n## Cyber Resilience Act statement\n\nMaraDNS is a project developed on a strictly volunteer, non-commercial\nbasis.  It has been developed outside the course of a commercial\nactivity, developed entirely in the Americas (i.e. *outside of Europe*)\nand therefore is not subject to the restrictions or conditions of the \nproposed EU Cyber Resilience Act.  Someone selling a product that \nuses any component of MaraDNS may be subject to this act and may\nneed to handle any and all necessary compliance.\n\nMaraDNS, as always, is provided free of charge but with **no warranty**.\n\n# Updates\n\n## 2022 Updates\n\nMaraDNS was updated in 2022 to have its automated tests run in an Ubuntu\n22.04 Docker container instead of an Ubuntu 20.04 Docker container.\nThe tests have also been updated to be more portable, running in both\nAlpine Linux (Busybox-based Linux distro) and Ubuntu 22.04.\n\nI also fixed a minor security issue, which also affected other DNS servers,\nwhere a clever attacker with access to the recurisve DNS server could had\nkept records in the cache longer than desired.\n\n`min_ttl` now correctly sets a minimum TTL for direct answers to queries.\nI have backported the `min_ttl` parameter to the older legacy 3.4 version\nof MaraDNS.\n\nWhile using Deadwood as a fully recursive server is not guaranteed to\nbe fully supported, I have fixed a long standing bug with how Deadwood\nhandled certain CNAME chains, and have added tests to make sure this\nbug stays fixed.\n\nMaraDNS no longer uses non-POSIX scripting languages not included \nwith MaraDNS:\n\n* MaraDNS’s documentation system, EJ, has been updated to use Lua 5.1\n  (included with MaraDNS with the name `lunacy` in `coLunacyDNS/lunacy`)\n  instead of Perl scripts.\n* The old `bind2csv2.py` tool has been removed, so that MaraDNS no\n  longer needs Python to run any of its components.\n\n## 2021 Updates\n\nDeadwood has a new parameter: `source_ip4`.  This optional parameter\nis used to specify the source IP when sending queries upstream.  The\nmajority of users should be able to leave this untouched; this is for\ncases when Deadwood is multi-homed and we need to specify which IP\nto use when querying root or upstream DNS servers.\n\nOne line change to zoneserver.c to make it work better with systemd.\n\nSynthetic IP generator example added to `coLunacyDNS`\n\n## 2020 Updates\n\nI have updated things so that the Git version of MaraDNS is the \nauthoritative “One source of truth” for MaraDNS’s source code.\nThe Git code is, every time a new MaraDNS release is made,\nconverted in to tarballs (with full Git history) which can be\ndownloaded at [Sourceforge](https://sourceforge.net/projects/maradns/)\nand [MaraDNS’s web page](https://maradns.samiam.org/download.html).\n\nI have added block list support to Deadwood, to allow a large list\nof host names to be blocked.\n\nI have created a new service: `coLunacyDNS`, a simple Lua-based DNS server\nwhich can return IPv4 (`A`) and IPv6 (`AAAA`) DNS records.  It has the\nability to query other DNS servers, and customize the answer given to\nthe client based on the contents of a Lua script.  All programs have IPv6\nsupport in Linux as well as *NIX clones, and the Windows 32-bit binary of\n`coLunacyDNS` has IPv6 support.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamboy%2FMaraDNS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamboy%2FMaraDNS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamboy%2FMaraDNS/lists"}