Kom igang med MREG-API'et

Hvis du skal automatisere/scripte bruken av Mreg, kan du gå rett mot APIet istedetfor å bruke en klient som f.eks. mreg-cli. Det er et REST-API, hvor du sender og mottar data i JSON-format. Først autentiserer du deg, da mottar du et "token". Dette "tokenet" bruker du i videre API-kall.

Eksemplene her bruker curl, men du kan bruke en hvilken som helst http-klient.

Autentisere

Man starter med å autentisere seg og motta et "token", slik:

curl -X POST -H "Content-Type: application/json" \
  --data "{\"username\":\"oyvihag-drift\",\"password\":\"$MYPASS\"}" \
  https://mreg.uio.no/api/token-auth/
  • Metode POST
  • Send med riktig content-type-header (application/json)
  • Send en JSON-struktur med brukernavn og passord som postdata
  • Husk å logge inn med driftsbruker hvis du trenger skriverettigheter

Du skal få tilbake et token:

{"token":"3c0b19cdef12384762384abcbdfbad76325"}

(Strengen som vises her er ikke et ekte token, bare et eksempel på hvordan det kan se ut)

Du bruker token-verdien til autentisering i videre API-kall.

Hente ut informasjon

APIet returnerer data i JSON-format.

Her er et eksempel som henter ut data om en gitt maskin:

curl -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
   "https://mreg.uio.no/api/v1/hosts/callisto.uio.no"
  • Http-metode GET

  • Send med http header "Authorization" med verdi "Token " + ditt token

  • Maskinnavnet i urlen

Tips: Hvis du bruker curl fra kommandolinjen kan du bruke jq til å formattere outputen:

curl -s -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
   "https://mreg.uio.no/api/v1/hosts/callisto.uio.no" | jq .

Lister og sidetall

Slik henter du en liste over alle maskiner:

curl -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
   "https://mreg.uio.no/api/v1/hosts/"

Obs! I utgangspunktet får du de 100 første, og så kan du be om "neste side" slik:

https://mreg.uio.no/api/v1/hosts/?page=2

Lenker til neste/forrige side finner du også i resultat-jsonen.

Du kan også endre sidestørrelsen til noe annet enn 100, men det er maks oppad begrenset til 1000:

https://mreg.uio.no/api/v1/hosts/?page_size=1000

Filtrering

# alle hoster med navn som starter på "nisse"
https://mreg.uio.no/api/v1/hosts/?name__startswith=nisse

# alle hoster med navn som ender på "ifi.uio.no"
https://mreg.uio.no/api/v1/hosts/?name__endswith=ifi.uio.no

# alle hoster med navn som matcher en regex
https://mreg.uio.no/api/v1/hosts/?name__regex=blue.*educloud

# alle hoster i en liste du oppgir
https://mreg.uio.no/api/v1/hosts/?name__in=saruman.uio.no,sauron.uio.no

Andre typer data

Eksemplene overfor er for hoster, men metodene fungerer noenlunde likt for alle de andre datatypene i Mreg også.

Her er en liste over de mest nyttige endepunktene du kan bruke:

Endepunkt Informasjon
cnames/ Liste over CNAME-oppføringer
cnames/<navn> Detaljvisning av et CNAME
dhcphosts/ipv4/ Hvilke mac-adresser som er koblet til hvilke ip-adresser og hoster (ipv4)
dhcphosts/ipv6/  
dhcphosts/ipv6byipv4/  
dhcphosts/<ip>/<range> Eksempel: dhcphosts/129.240.202.0/23
hosts/ Liste ut host-objekter
hosts/<name> Detaljert informasjon om et gitt hostobjekt
hostgroups/  
hostgroups/<name>  
networks/ Liste over definerte subnett
networks/ip/<ip> F.eks: networks/ip/129.240.202.63 , gir info om subnettet adressen tilhører.
networks/<subnett>/ Detaljinfo. Eksempel: networks/129.240.202.0/23
networks/<subnett>/random_unused Returnerer en tilfeldig, ubrukt adresse på subnettet
(NB! Adressen blir ikke reservert)
networks/<subnett>/first_unused Returnerer første ubrukte adresse på subnettet
(NB! Adressen blir ikke reservert)

networks/<subnett>/used_host_list

Lister ut alle maskiner på subnettet

For en fullstendig liste over alle endepunkter som er tilgjengelige, se i kildekoden her og her.

Lage host-objekter

Slik oppretter du et host-objekt:

curl -D - -X POST \
     -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
     -H "Content-Type: application/json" \
     --data '{"name":"minmaskin.uio.no",
        "ipaddress":"123.123.123.123",
        "contact":"oyvind.hagberg@usit.uio.no",
        "comment":"bare en test"}' \
     https://mreg.uio.no/api/v1/hosts/
  • Metode POST
  • Send med http header "Authorization" med verdi "Token " + ditt token
  • Husk riktig content-type
  • Post data skal være en JSON-struktur som må inneholder minimum "name", "contact" og "comment"

Sjekk http-statusverdien for å se om kallet gikk bra. Du skal få 201 Created hvis alt gikk bra.

Endre kontaktinfo og kommentar

Hvis du prøver en http post til /api/v1/hosts/.... tolkes det som at du forsøker å opprette et nytt host-objekt. Da får du feilmelding om at "name already in use". Derfor, hvis du vil endre på et objekt, må du bruke patch-metoden.

Kommandoen "host set_comment" i mreg-cli tilsvarer en http patch til /api/v1/hosts/hostnavn.uio.no med body { "comment": "ny kommentar" }.
"host set_contact" blir da en tilsvarende forespørsel bare med "contact" i body. Man kan også sette begge feltene i samme forespørsel.
Eksempel:

curl -D - -X PATCH \
 -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
 -H "Content-Type: application/json" \
 --data '{"contact":"nykontaktadresse@uio.no",
          "comment":"Ny kommentar"}' \
 https://mreg.uio.no/api/v1/hosts/minmaskin.uio.no

HTTP/1.1 204 No Content
...

Feltet contact kan ikke være flere email-adresser dessverre, kun én. Verdien valideres, så den må se ut som en ekte email-adresse eller være tom.
Http-statuskoden som du får tilbake skal være noe i 200-serien hvis operasjonen gikk bra.

Tips: For å endre navnet på en host kan du gjøre en patch til /api/v1/hosts/gammeltnavn.uio.no med body { "name": "nyttnavn.uio.no" }.

Legge til og fjerne roller på maskiner

Legge til en rolle (host policy) på en maskin:

curl -D - -X POST \
     -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
     -H "Content-Type: application/json" \
     --data '{"name":"hostnavn.uio.no"}' \
     'https://mreg.uio.no/api/v1/hostpolicy/roles/ROLLENAVN/hosts/'

HTTP/1.1 201 Created
Server: nginx/1.16.1
...
  • Oppgi hostnavnet i JSON.
  • Rollen/hostpolicyen legges i urlen. Rollen må selvsagt finnes fra før av i Mreg.
  • POST metode, og husk Content-Type header
  • Sjekk http-statuskoden som du får tilbake. Skal være 201 hvis operasjonen gikk bra.

Fjerne en maskin fra en rolle/hostpolicy:

curl -D - -X DELETE \
     -H "Authorization: Token 3c0b19cdef12384762384abcbdfbad76325" \
     'https://mreg.uio.no/api/v1/hostpolicy/roles/ROLLENAVN/hosts/hostnavn.uio.no'

HTTP/1.1 204 No Content
  • DELETE metode. Du sender ikke med noe innhold, så du trenger ikke content-type-headeren her.
  • Kontroller at du får http status 204 i retur, det betyr at operasjonen gikk bra.

Videre

Vi kommer til å skrive mer på dette dokumentet etterhvert som behovet melder seg. Send gjerne epost til usit-gid@rt.uio.no om hva du ønsker dokumentert.

Publisert 2. juli 2020 10:48 - Sist endret 13. aug. 2021 12:37