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! 亚博娱乐官网_亚博pt手机客户端登录n blir ikke reservert)
networks/<subnett>/first_unused Returnerer f?rste ubrukte adresse p? subnettet
(NB! 亚博娱乐官网_亚博pt手机客户端登录n 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