Nivlheim Innsamlede konfigurasjonsfiler fra UiO-maskiner
Menu

API-funksjoner

  1. select
  2. hostinfo2 Mye nytt her!
  3. lastseen

Alle API-funksjoner bruker HTTP Basic authentication. Lag dine egne API-nøkler og bruk dem som brukernavn/passord ved API-kall.

select

https://nivlheim.uio.no/api/select

Denne funksjonen er et tynt skall som ligger utenpå Solr sitt web-baserte API. Det ivaretar tilgangskontroll og sørger for å legge på nødvendige parametre som begrenser hvilke data brukeren får lov til å hente ut.

Vanlige parametre:

ParameterEksempelverdiBetydning
q*:*Fritekstsøk / "fuzzy" søk, i de feltene som støtter det
fqfilename:"/etc/uio/info/rpm-packages.txt"Konkret begrensning for søket. Et felt skal ha en gitt verdi. Du kan ha flere av disse!
iprange129.240.6.0/24Begrense søket til et visst ip-område. Du kan bruke IPv4 eller IPv6.
flhostname,filenameKommaseparert liste over hvilke felter vi vil ha tilbake i resultatet
rows20Begrensning for antall dokumenter vi ønsker å få tilbake. Default er 10.
start0Hvilken "offset"/hvor langt ute i resultatet vi ønsker å se dokumenter fra. Brukes sammen med rows for å returnere deler/sider av det totale resultatet.
wtjsonHvilket format vi ønsker resultatet på. Støtter bl.a. json, xml og csv.
indent1Hvis wt=json og man ønsker pent indentert kode tilbake, sett denne =1.
sorthostname ascHvordan resultatet skal sorteres. Feltnavn + asc/desc.

For resten av parametrene og en forklaring på dem, les Apache Solr-dokumentasjonen. select fungerer med få unntak på akkurat samme måte som originalfunksjonen i Apache Solr. Dokumentasjon på hvordan man bruker den finnes i Apache Solr Reference Guide, les avsnittet "Common Query Parameters".

Pro tip: select godtar også å få parametrene som en JSON-struktur via HTTP POST, hvis man foretrekker det fremfor å putte parametrene i urlen.

Det er nødvendig å kjenne til dokumentskjemaet i Nivlheim sitt Solr-oppsett:

Navn Datatype Beskrivelse Hvordan man kan søke på det
git_commit_id string Git sin commit-id, fra arkivet. Hex string Eksakt match kreves ved søk
git_commit_time datetime Tidspunktet denne filen ble lagret i arkivet. Man kan søke på datoområder. Les avsnittet "Working with dates" i Solr Reference Guide.
cert_fingerprint string Klientsertifikatets fingerprint. Hex string Eksakt match kreves ved søk
ipaddr string ip-adressen til klienten. I tilfelle en maskin bytter ip-adresse, er det adressen den hadde på det tidspunktet filene ble levert inn. Eksakt match kreves ved søk. Se også parameteren iprange til select-funksjonen.
hostname string Hostnavn inkl. domene (eksempel.uio.no). I tilfelle en maskin bytter navn er det nåværende navn som gjelder. Treff kun på hostnavn inkl. domene
hostonly text Hostnavn uten domene. Kun til søk, feltet returneres ikke i resultatet Treff på hostnavn uten domene
filename string Filnavn inkl path (/etc/passwd) Matcher på hele filnavnet inkl path, eller deler av pathen (fra toppnivå og nedover).
content text Innholdet av filen Fritekstsøk. For info om hvor søket traff, les avsnittet "Highlighting" i Solr Reference Guide.
is_command boolean false hvis dette er innholdet av en fil, true hvis dette er outputen fra en kommando  
current boolean true hvis dette er den nyeste versjonen av filen, false hvis dette er en eldre versjon. Legg på fq=current:true som parameter dersom du kun er interessert i treff på siste (current) versjon
subnet string, multivalue navn på subnett som maskinens ip-adresse tilhører. Hentet fra CFEngine-config. Eksakt match på minst ett av subnett-navnene (f.eks. fys_networks)
subnet_comment text, multivalue Kommentarer til subnettene fra CFEngine-configfilen Fritekstsøk
id string unik id, genereres ut i fra andre felter (git commit id, cert fingerprint, filename) Eksakt match kreves ved søk
_version_ long Solr krever dette feltet til internt bruk.  
owner string eier-id, til intert bruk for tilgangskontroll Kriterie for dette vil bli lagt på automatisk av API'et og er ikke mulig å overstyre.

Eksempler

Hente maskiner i et gitt ip-område:

https://nivlheim.uio.no/api/select?q=*:*&iprange=129.240.6.0/24 &fl=ipaddr,hostname&group=true&group.field=ipaddr&group.ngroups=true&group.main=true &rows=50&sort=ipaddr%20asc
https://nivlheim.uio.no/api/select?q=*:*&iprange=2001:700:111::/48 &fl=ipaddr,hostname&group=true&group.field=ipaddr&group.ngroups=true&group.main=true &rows=50&sort=ipaddr%20asc

Finne maskiner med en viss kernelversjon:

https://nivlheim.uio.no/api/select?q=content:2.6.32 &fl=hostname&fq=filename:"/etc/uio/info/uname-info.txt" &fq=current:true&wt=csv&csv.header=false
https://nivlheim.uio.no/api/select?q=content:6.3.9600.0 &fl=hostname&fq=filename:%22[System.Environment]::OSVersion%20|%20Format-List%22 &fq=current:true&wt=csv&csv.header=false

Finne maskiner i et navngitt subnett. Subnett-navn hentes fra CFEngine-konfigurasjonen: /var/cfengine/inputs/variables.cf. F.eks.: uio_wired, matte_networks

https://nivlheim.uio.no/api/select? q=*:*&fq=subnet:geo_networks&fl=hostname,ipaddr&group=true &group.ngroups=true&group.field=hostname&rows=100&sort=hostname%20asc

lastseen

Denne funksjonen er utgått. Bruk hostinfo2 i stedet. Funksjonen ble brukt til å returnere tidspunktet for når Nivlheim sist fikk inn filer fra den/de angitte maskinen(e).

hostinfo2

hostinfo2 gir standardisert informasjon om maskiner.

Hente ut all informasjon om en gitt maskin:

https://nivlheim.uio.no/api/hostinfo2?hostname=scan.uio.no
{ "result" : [ { "certfp" : "2B00DBFF8A98EDDAEBF301A3C819F7269DDD4B40", "serial" : "1TMQ55J", "daysLeftOfWarranty" : 575, "siteadmin" : "cert@usit.uio.no", "hostname" : "scan.uio.no", "os" : "RHEL7", "kernel" : "3.10.0-123.13.2.el7.x86_64", "manufacturer" : "Dell Inc.", "lastseen" : "2015-03-20T08:22:53Z", "type" : "Server", "product" : "PowerEdge M610", "ipaddr" : "129.240.2.74", "warranty" : [ { "active" : true, "description" : "ProSupport for End Users and 4hr Mission Critical", "daysleft" : 575, "start" : "2011-10-14T19:00:00", "expires" : "2016-10-15T18:59:59" }, { "active" : false, "description" : "Next Business Day", "daysleft" : -155, "start" : "2011-10-14T19:00:00", "expires" : "2014-10-15T18:59:59" }, { "active" : false, "description" : "ProSupport for End Users and 4hr Mission Critical", "daysleft" : -155, "start" : "2011-10-14T19:00:00", "expires" : "2014-10-15T18:59:59" } ] } ] }

Begrense hvilke felter som returneres:

Kun interessert i visse felter? Bruk parameteren fl.
Eksempel: Hente ut "last seen", dvs finne ut tidspunktet når Nivlheim sist hørte noe fra en maskin:
https://nivlheim.uio.no/api/hostinfo2?hostname=scan.uio.no&fl=hostname,lastseen
{ "result" : [ { "hostname" : "scan.uio.no", "lastseen" : "2015-03-20T08:22:53Z" } ] }

Alle maskiner

Vil du ha en liste med "lastseen" for alle maskiner? Bare la vær å angi hostname. Slik:
https://nivlheim.uio.no/api/hostinfo2?fl=hostname,lastseen
Liste over all informasjon for alle maskiner (NB! Mye data, tar litt tid)
https://nivlheim.uio.no/api/hostinfo2

Wildcard i søk

Alle Windowsmaskiner, unntatt de som kjører Windows 7:
https://nivlheim.uio.no/api/hostinfo2?os=win*&os!=win7&fl=hostname,os
Alle HP-servere (type-feltet fungerer foreløpig kun på Linux):
https://nivlheim.uio.no/api/hostinfo2?manufacturer=hewlett*&type=server&fl=hostname,product
Alle maskiner som tilhører GSD:
https://nivlheim.uio.no/api/hostinfo2?siteadmin=*gsd*&fl=hostname,siteadmin,os

Grupper og tell resultater

Angi parameteren count=1 og angi et eller flere felter med fl-parameteren.
Eksempel: Liste over hardware-leverandører og antall maskiner fra hver:
https://nivlheim.uio.no/api/hostinfo2?fl=manufacturer&count=1
Liste over operativsystemer og antall maskiner med hvert:
https://nivlheim.uio.no/api/hostinfo2?fl=os&count=1

Asynkrone kall?

Send med en streng og få den tilbake i svaret (praktisk i asynkrone kall, som f.eks. i Javascript i en nettleser):
https://nivlheim.uio.no/api/hostinfo2?hostname=ulrik.*&fl=hostname,lastseen&passthru=hei%20dette%20er%20min%20tekst

Logisk ELLER istedetfor OG

Angi parameteren any=1, så holder det at ett av kriteriene oppfylles, i motsetning til alle.
https://nivlheim.uio.no/api/hostinfo2?os=debian*&os=fedora*&any=1&fl=os&count=1