mreg

mreg is an API (intended to be as RESTful as possible) for managing DNS.

An associated project for a command line interface using the mreg API is available at: mreg-cli

Getting Started

Prerequisites

If you want to set up your own PostgreSQL server by installing the necessary packages manually, you might need to install dependencies for setting up the citext extension. On Fedora, the package is called postgresql-contrib.

Installing

Using Docker

Pre-built Docker images are available from ghcr.io/unioslo/mreg:

docker pull ghcr.io/unioslo/mreg

You can also build locally, from the source:

docker build -t mreg .

It is expected that you mount a custom "mregsite" directory on /app/mregsite:

docker run \
  --mount type=bind,source=$HOME/customsettings,destination=/app/mregsite,readonly \
  ghcr.io/unioslo/mreg:latest

To access application logs outside the container, also mount /app/logs.

It is also possible to not mount a settings directory, and to supply database login details in environment variables instead, overriding the default values found in mregsite/settings.py.

docker run --network host \
  -e MREG_DB_HOST=my_postgres_host -e MREG_DB_NAME=mreg -e MREG_DB_USER=mreg -e MREG_DB_PASSWORD=mreg \
  ghcr.io/unioslo/mreg:latest

For a full example, see docker-compose.yml.

Manually

Tip

Depending on your operating system, you may need to install additional packages to get the necessary dependencies for the project. At the very least you will probably require development packages for Python 3.

A step by step

Start by cloning the project from github. You need a terminal and the uv package manager.

Important

mreg relies on PEP 735 dependency groups for development, which is not supported by pip as of version 24.3.1.

When you've got your copy of the mreg directory, set up the venv and install the dependencies:

uv sync --frozen

Activate the venv (optional)

Optionally, you can also activate the created virtual environment. However, we will use uv run to run the commands in the virtual environment in this guide, which foregoes the need to activate the environment.

. .venv/bin/activate

Activating the venv allows you to run the commands with python instead of uv run.

Perform database migrations:

uv run manage.py migrate

Load sample data from fixtures into the now migrated database:

uv run manage.py loaddata mreg/fixtures/fixtures.json

And finally, run the server:

uv run manage.py runserver

You should now be able to open up a browser and go to http://localhost:8000/hosts/ and see a list of hosts provided by the sample data. Or, you could perform a GET request to see the returned data.

curl -X GET http://localhost:8000/hosts/

[{"name":"ns1.uio.no"},{"name":"ns2.uio.no"},{"name":"lucario.uio.no"},{"name":"stewie.uio.no"},{"name":"vepsebol.uio.no"}]

Running the tests

To run the tests for the system, simply run

uv run manage.py test

Local Settings

To override entries in mregsite/settings.py, create a file mregsite/local_settings.py and add the entries there. For example, the default database setup in settings.py uses sqlite3, but if you set up your postgres database you'll want to override this when testing. To to this, just add the following to your local_settings.py file:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mreg_sample',
        'USER': 'mreg_user',
        'PASSWORD': 'mregdbpass',
        'HOST': 'localhost',
    }
}

Contributing

Patches and PRs are welcome. However, there are a number of intricacies in both code structure and internal expectations, so you should probably get in touch with the project maintainers before you start working on anything major. If in doubt, open an issue to start a discussion.

See CONTRIBUTING.md for more information.

Reference material

• NS, 1
• NS, 2
• SOA
• A / AAAA
• CNAME
• PTR
• HINFO
• NAPTR
• SRV
• TXT
• LOC
• Other DNS record types
• Telephone number mapping/ENUM

Authors

• Øyvind Hagberg
• Øyvind Kolbu
• Paal Braathen
• Geir Ulvik
• Nils Hiorth
• Nicolay Mohebi
• Magnus Hirth
• Marius Bakke
• Safet Amedov
• Tannaz Roshandel
• Terje Kvernes

License

This project is licensed under the GPL-3.0 License - see the LICENSE.md file for details

Acknowledgments

• Django
• Django Rest Framework