MAAS Internal URLs

Introduction

There are a number of internal URLs MAAS uses during commissioning and deployment which are useful to access when debugging. This document describes what they are and how to access them.

Static files

All bootloaders, images, kernels, and initrds found in /var/lib/maas/boot-resources/current on the rack controller are available over both HTTP and TFTP. Directory listing is enabled over HTTP

http://$RACK:5248/images/
tftp://$RACK/

Bootloader configuration files

All bootloader configuration files are available over TFTP and are generated dynamically by the rack controller. The default configuration is used during enlistment. For any other state the MAC address must be included in the request.

PXELinux i386, AMD64

tftp://$RACK/pxelinux.cfg/default
http://$RACK:5248/pxelinux.cfg/default
# MAC is delaminated with a '-' e.g 52-54-00-20-b1-01
tftp://$RACK/pxelinux.cfg/01-$MAC
http://$RACK:5248/pxelinux.cfg/01-$MAC

GRUB UEFI AMD64, ARM64

tftp://$RACK/grub/grub.cfg-default-amd64
http://$RACK:5248/grub/grub.cfg-default-amd64
# MAC is delaminated with a ':' e.g 52:54:00:dd:d1:50
tftp://$RACK/grub/grub.cfg-$MAC
http://$RACK:5248/grub/grub.cfg-$MAC

PowerNV/PPC64EL

tftp://$RACK/ppc64el/pxelinux.cfg/default
http://$RACK:5248/ppc65el/pxelinux.cfg/default
# MAC is delaminated with a '-' e.g 52-54-00-20-b1-01
tftp://$RACK/ppc64el/pxelinux.cfg/01-$MAC
http://$RACK:5248/ppc64el/pxelinux.cfg/01-$MAC

s390x

tftp://$RACK/s390x-dpm.cfg/$LPAR_UUID
http://$RACK:5248/s390x-dpm.cfg/$LPAR_UUID

s390x DPM Partition

There is only one URL for both known and unknown machines. MAAS will automatically detect a known machine by the MAC address used in the connection to MAAS.

tftp://$RACK/s390x_partition/maas
http://$RACK:5248/s390x_partition/maas

Metadata server

MAAS implements a subset of the EC2 metadata service to provide machines with data such as hostname, SSH keys, and user data to be run. Only a subset of data can be accessed anonymously, most data requires OAUTH1 credentials.

Accessing the metadata server

As of MAAS 2.5 each rack controller runs an nginx HTTP proxy service which allows machines to only have to interact with the rack controller.

Metadata directly from the region

http://$REGION:5240/MAAS/metadata/latest/

Metadata through the nginx proxy

http://$RACK:5248/MAAS/metadata/latest

Preseeds

The preseed contains the initial configuration for cloud-init to configure the system. Two URLs are available, one during enlistment and another used by all other environments.

http://$REGION:5240/MAAS/metadata/latest/enlist-preseed/?op=get_enlist_preseed
http://$REGION:5240/MAAS/metadata/latest/by-id/$SYSTEM_ID/?op=get_preseed

Userdata

The userdata contains scripts and other configuration data which is run by cloud-init. MAAS creates userdata by starting with a template and adding additional required data. These templates can be found in

/etc/maas/preseeds/*userdata*

The data is then base64 encoded and returned to the client.

Enlistment userdata

Enlistment userdata can be access anonymously

http://$REGION:5240/MAAS/metadata/enlist/latest/user-data

Userdata for Curtin(deploying)

http://$REGION:5248/MAAS/curtin/latest/user-data

Userdata for all other ephemeral environments

This method requires OAUTH1 credentials

http://$REGION:5240/MAAS/metadata/latest/user-data

Internal SimpleStreams mirror

The MAAS region provides all rack controllers with images by creating a SimpleStream with the images an administrator has selected to be downloaded. Like images.maas.io an index.json is provided however only one product stream is created.

http://$REGION:5240/MAAS/images-stream/streams/v1/index.json
http://$REGION:5240/MAAS/images-stream/streams/v1/maas:v2:download.json

Images can be downloaded by concatenating the images-streams endpoint with the path in the product stream. For example

http://$REGION:5240/MAAS/images-stream/ubuntu/amd64/hwe-18.04/bionic/20200831/squashfs
3 Likes

@ltrager, okay if i makde this part of the doc?

I wrote this mainly for MAAS developers as the URLs are useful for debug. I don’t see a reason not to include it in the docs though.

2 Likes

I know it is over 3 years old, but very, very helpful. With the combination of this and https://perso.citi-lab.fr/sdalu/sysadmin/dnsmasq/, I was able to setup my dnsmasq (pihole) as the dhcp server, which has to provide all of these urls. I would love to see an up2date/exhaustive version of this list.

For reference, this is what I ended up with:

# /etc/dnsmasq.d/90-pxe-boot.conf
# mass server at 192.168.1.111

# Interface: bios, uefi, uboot, open-firmware, epapr, opal
dhcp-match=set:bios,          option:client-arch, 0
dhcp-match=set:bios,          option:client-arch, 20
dhcp-match=set:uefi,          option:client-arch, 6
dhcp-match=set:uefi,          option:client-arch, 7
dhcp-match=set:uefi,          option:client-arch, 9
dhcp-match=set:uefi,          option:client-arch, 10
dhcp-match=set:uefi,          option:client-arch, 11
dhcp-match=set:uefi,          option:client-arch, 15
dhcp-match=set:uefi,          option:client-arch, 16
dhcp-match=set:uefi,          option:client-arch, 17
dhcp-match=set:uefi,          option:client-arch, 18
dhcp-match=set:uefi,          option:client-arch, 19
dhcp-match=set:uefi,          option:client-arch, 25
dhcp-match=set:uefi,          option:client-arch, 26
dhcp-match=set:uefi,          option:client-arch, 27
dhcp-match=set:uefi,          option:client-arch, 28
dhcp-match=set:uefi,          option:client-arch, 29
dhcp-match=set:uefi,          option:client-arch, 30
dhcp-match=set:uefi,          option:client-arch, 33
dhcp-match=set:uefi,          option:client-arch, 34
dhcp-match=set:uefi,          option:client-arch, 35
dhcp-match=set:uefi,          option:client-arch, 36
dhcp-match=set:uboot,         option:client-arch, 21
dhcp-match=set:uboot,         option:client-arch, 22
dhcp-match=set:uboot,         option:client-arch, 23
dhcp-match=set:uboot,         option:client-arch, 24
dhcp-match=set:open-firmware, option:client-arch, 12
dhcp-match=set:epapr,         option:client-arch, 13
dhcp-match=set:opal,          option:client-arch, 14

# Architecture: i386, x86_64, efi_bytecode, arm_32, arm_64,
#               powerpc, riscv_32, riscv_64, riscv_128,
#               s390_basic, s390_extended, mips_32, mips_64,
#               sunway_32, sunway_64
dhcp-match=set:i386,          option:client-arch, 0
dhcp-match=set:i386,          option:client-arch, 6
dhcp-match=set:i386,          option:client-arch, 15
dhcp-match=set:i386,          option:client-arch, 20
dhcp-match=set:x86_64,        option:client-arch, 7
dhcp-match=set:x86_64,        option:client-arch, 16
dhcp-match=set:efi_bytecode,  option:client-arch, 9
dhcp-match=set:efi_bytecode,  option:client-arch, 17
dhcp-match=set:arm_32,        option:client-arch, 10
dhcp-match=set:arm_32,        option:client-arch, 18
dhcp-match=set:arm_32,        option:client-arch, 21
dhcp-match=set:arm_32,        option:client-arch, 23
dhcp-match=set:arm_64,        option:client-arch, 11
dhcp-match=set:arm_64,        option:client-arch, 19
dhcp-match=set:arm_64,        option:client-arch, 22
dhcp-match=set:arm_64,        option:client-arch, 24
dhcp-match=set:powerpc        option:client-arch, 12
dhcp-match=set:powerpc        option:client-arch, 13
dhcp-match=set:powerpc        option:client-arch, 14
dhcp-match=set:riscv_32,      option:client-arch, 25
dhcp-match=set:riscv_32,      option:client-arch, 26
dhcp-match=set:riscv_64,      option:client-arch, 27
dhcp-match=set:riscv_64,      option:client-arch, 28
dhcp-match=set:riscv_128,     option:client-arch, 29
dhcp-match=set:riscv_128,     option:client-arch, 30
dhcp-match=set:s390_basic,    option:client-arch, 31
dhcp-match=set:s390_extended, option:client-arch, 32
dhcp-match=set:mips_32,       option:client-arch, 33
dhcp-match=set:mips_64,       option:client-arch, 34
dhcp-match=set:sunway_32,     option:client-arch, 35
dhcp-match=set:sunway_64,     option:client-arch, 36

# Client: pxe, http
dhcp-vendorclass=set:pxe,     PXEClient
dhcp-vendorclass=set:http,    HTTPClient

dhcp-match=set:http,          option:client-arch, 15
dhcp-match=set:http,          option:client-arch, 16
dhcp-match=set:http,          option:client-arch, 17
dhcp-match=set:http,          option:client-arch, 18
dhcp-match=set:http,          option:client-arch, 19
dhcp-match=set:http,          option:client-arch, 20
dhcp-match=set:http,          option:client-arch, 23
dhcp-match=set:http,          option:client-arch, 24
dhcp-match=set:http,          option:client-arch, 26
dhcp-match=set:http,          option:client-arch, 28
dhcp-match=set:http,          option:client-arch, 30


dhcp-userclass=set:freebsd,    FreeBSD           # FreeBSD `loader.efi`
dhcp-userclass=set:ipxe,       iPXE              # iPXE
dhcp-match=set:ipxe, 175


dhcp-option-force=tag:http,60,HTTPClient

# By default load the iPXE implementation
# - from PXEClient
dhcp-boot=tag:pxe, tag:uefi,tag:i386,  lpxelinux.0        ,,192.168.1.111
dhcp-boot=tag:pxe, tag:uefi,tag:x86_64,bootx64.efi        ,,192.168.1.111
dhcp-boot=tag:pxe, tag:bios,           lpxelinux.0         ,,192.168.1.111
# - from HTTPClient
dhcp-boot=tag:http,tag:uefi,tag:i386,  http://192.168.1.111:5248/pxelinux.cfg/default
dhcp-boot=tag:http,tag:uefi,tag:x86_64,http://192.168.1.111:5248/grub/grub.cfg-default-amd64
dhcp-boot=tag:http,tag:bios,           http://192.168.1.111:5248/pxelinux.cfg/default


# TODO raspberry
# https://discourse.maas.io/t/maas-internal-urls/176

EDIT: HTTP boot in MAAS was also very helpful