NAS Bestellung via REST API

Allgemeine Information

Aktuell ist die API nur für ETHZ Mitarbeiter freigegeben, Studenten können die Schnittstelle nicht benutzen.

Authentifizierung

Der Webservice benutzt Basic Authentication der ETHZ AD Domain als Authorisierung, womit sie einfach ihr ETH Userkonto benutzen können (inklusive Domain).

Beispiel:
Username: mmuster@ethz.ch
Passwort: xxxxxxx

Auslesen der bestehenden NAS Shares GET

Beschreibung: Es werden die NAS Shares ausgelesen, welche von der angemeldeten Person erstellt worden sind.

URL: https://itshopwsvc.ethz.ch:44348/api/nas

Auslesen eines dedizierten NAS Shares GET

Beschreibung: Es wird der angegebene NAS Shares ausgelesen, sofern die angemeldete Person Besitzer (Owner) oder in der adminGroup des Shares ist.

URL: https://itshopwsvc.ethz.ch:44348/api/nas/{sharename}

Bestellung eines NAS Shares POST

Beschreibung: Es wird ein neuer NAS Share bestellt. Die angemeldete Person kann auch Shares für andere Personen bestellen.

Bedingungen/Einschränkungen:

name (der Sharename setzt sich aus [ou]_[institut]_[suffix] zusammen und muss vollständig angegeben werden), wobei das Institut der OU angegliedert sein muss)
approvalData (sapElement & sapApprover müssen zusammenpassen)
adminGroup (der User muss in der angegebenen Admingruppe enthalten sein)

URL: https://itshopwsvc.ethz.ch:44348/api/nas

Content-Type: application/json

Syntax und Semantik der einzelnen Parameter im body

Name	Obligatorisch	Syntax	Semantik
name	ja	String, beginnend mit orgUnit, danach institute und suffix, jeweils durch Unterstrich getrennt	bestimmt den eindeutigen Namen des Shares
sizeInGB	ja	natürliche Zahl	Grösse des Shares in GiB
inodes	ja	natürliche Zahl	maximale Anzahl möglicher Dateien und Ordner im Share
thresholdInPercent	nein	0..100	Prozentwert gegen welchen die belegte Grösse und die belegten inodes täglich geprüft werden. Bei Überschreitung wird ein E-Mail ausgelöst
adminGroup	ja	String, AD Gruppenname (ohne Domain)	Berechtigungsgruppe auf dem Filesystem und im IT Shop (Modification/Deletion)
storageClass	ja	QoS1
location	ja	RZ \| HIT
snapshotPolicy	nein	dailySnapshot \| noSnapshot	Regel für Disk-basierte Snapshots
backupPolicy	nein	dailyBackup \| noBackup	Regel für Band-basierte Datensicherung
sapElement	ja	5-stellige Kostenstelle beginnend mit 2 oder 12-stelliges PSP Element inkl. Bindestrich	verrechnungs-relevante Information
sapApprover	ja	Primäres E-Mail-Konto / UPN	verrechnungs-relevante Information
approvalReason	nein	String	Information für den Bewilliger in Ethis
(cifs) enabled	nein	false \| true	Für den Share wird ein CIFS/SMB Export angelegt
(cifs) browsable	nein	false \| true	Der Share wird im Windows-Explorer beim Browsen des Servers angezeigt
(cifs) shareComment	nein	String	Der Kommentar ist beim Browsen des Servers neben dem Namen sichtbar
(cifs) hideUnreadable	nein	false \| true	Alle Dateien und Verzeichnisse, für die der Benutzer keine Lese-Berechtigung hat, sind aus den Verzeichnislisten ausgeblendet
(cifs) enableDFS	nein	false \| true	Für den Share wird ein DFS Eintrag angelegt welcher auf den Share zeigt
(cifs) dfsPath	nein	String, nur Pfadteil subOu\link	Unter diesem Namen wird der DFS Eintrag angelegt: \\d.ethz.ch\groups\subOu
(cifs) domain	nein	D	AD Domain der nachfolgenden Berechtigungsgruppe; immer 'D'
(cifs) groupName	nein	String, AD Gruppenname (ohne Domain)	Die Gruppe erhält einen Eintrag in den 'share permissions' und in der ACL des Filessytems
(cifs) access	nein	Allowed
(cifs) permission	nein	Full \| Change \| Read	Berechtigungsstufe bei den 'share permissions'
(nfs) enabled	nein	false \| true	Für den Share wird ein NFS Export angelegt
(nfs) client	nein	Hostname, IP-Adresse , subnet (CIDR Notation) oder netgroup	Der/die benannte/n Client/s erhält/erhalten Zugriff auf den Export
(nfs) accessType	nein	RO \| RW	Berechtigungsstufe: Nur-Lesen oder Lese-/Schreibzugriff
(nfs) squash	nein	no_root_squash \| root_squash	Behandlung beim Zugriff auf den Export als Benutzer root: root_squash: die ID für root wird auf die höchste UID gemappt no_root_squash: die ID für root wird auf UID ‘0’ gemappt. Der Benutzer agiert auf dem Share als root.
(nfs) priviledgedPorts	nein	false \| true	Ports < 1024 gelten als privileged und können vom Client nur genutzt werden wenn der Parameter auf 'true' gesetzt wird
(nfs) protocolVersion	nein	v3_sys \| v4_krb5 \| v4_sys_krb5	Regelt das mögliche Zugriffsprotokoll und den Security-Typ für den Client
user	nein	ETH Username (ohne Domain)	der User wird zum Owner des Shares (Automatisch der Ausführer des Requests, kann aber auch separat gesetzt werden)
orgUnit	ja	OuName gem. IT Shop	organisatorische Zugehörigkeit des Shareowners (siehe "user" Property oben)

POST Example - CIFS Export

{
  "name": "phys_astro_experiments",
  "sizeInGB": 1024,
  "inodes": 1024,
  "thresholdInPercent": 95,
  "adminGroup": "ID-PPF-NAS-FileShare",
  "storageClass": "QoS1",
  "location": "RZ",
  "snapshotPolicy": "dailySnapshot",
  "backupPolicy": "dailyBackup",
  "approvalData": {
    "sapElement": "nnnnn",
    "sapApprover": "approver@ethz.ch",
    "approvalReason": "Fileablage fuer experimentelle Daten"
  },
  "cifsExportData": {
    "enabled": true
	"browsable": true,
    "shareComment": "Fileablage fuer experimentelle Daten",
    "hideUnreadable": false,
    "enableDFS": false,
    "dfsPath": "",
    "permissions": [
      {
        "domain": "D",
        "groupName": "ID-PPF-NAS-FileShare",
        "access": "Allowed",
        "permission": "Full"
      }
    ]
  },
  "nfsExportData": {
    "enabled": false
  },
  "user": "mmuster",
  "orgUnit": "phys"
}

POST Example - NFS Export

{
  "name": "phys_astro_experiments",
  "sizeInGB": 1024,
  "inodes": 1024,
  "thresholdInPercent": 95,
  "adminGroup": "ID-PPF-NAS-FileShare",
  "storageClass": "QoS1",
  "location": "RZ",
  "snapshotPolicy": "dailySnapshot",
  "backupPolicy": "dailyBackup",
  "approvalData": {
    "sapElement": "nnnnn",
    "sapApprover": "approver@ethz.ch",
    "approvalReason": "Fileablage fuer experimentelle Daten"
  },
  "cifsExportData": {
    "enabled": false
  },
  "nfsExportData": {
    "enabled": true,
    "permissions": [
      {
        "client": "my-client.ethz.ch",
        "accessType": "RO",
        "squash": "no_root_squash",
        "priviledgedPorts": true,
        "protocolVersion": "v3_sys"
      }
    ]
  },
  "user": "mmuster",
  "orgUnit": "phys" 
}

Ändern eines NAS Shares PUT

Beschreibung: Es werden Paramter des angegebenen, bestehenden Shares geändert

Bedingungen/Einschränkungen:

Der User muss Besitzer (Owner) des Shares oder in der Admingruppe enthalten sein

URL: https://itshopwsvc.ethz.ch:44348/api/nas/

Content-Type: application/json

Syntax und Semantik der einzelnen Parameter im body

Name	Obligatorisch	Syntax	Semantik
name	ja	String, beginnend mit orgUnit, danach institute und suffix, jeweils durch Unterstrich getrennt	eindeutiger Name des Shares
sizeInGB	nein	natürliche Zahl	neue Grösse des Shares in GiB
inodes	nein	natürliche Zahl	neue maximale Anzahl möglicher Dateien und Ordner im Share
thresholdInPercent	nein	0..100	neuer Prozentwert gegen welchen die belegte Grössun und die belegten inodes täglich geprüft werden. Bei Überschreitung wird ein E-Mail ausgelöst
adminGroup	nein	String, AD Gruppenname (ohne Domain)	neue Berechtigungsgruppe auf dem Filesystem und im IT Shop (Modification/Deletion)
snapshotPolicy	nein	dailySnapshot \| noSnapshot	neue Regel für Disk-basierte Snapshots
backupPolicy	nein	dailyBackup \| noBackup	neue Regel für Band-basierte Datensicherung
sapElement	nein	5-stellige Kostenstelle beginnend mit 2 oder 12-stelliges PSP Element inkl. Bindestrich	verrechnungs-relevante Information
sapApprover	nein	Primäres E-Mail-Konto / UPN	verrechnungs-relevante Information
approvalReason	nein	String	Information für den Bewilliger in Ethis
(cifs) enabled	nein	false \| true	Für den Share wird ein CIFS/SMB Export angelegt oder entfernt
(cifs) browsable	nein	false \| true	Der Share wird im Windows-Explorer beim Browsen des Servers angezeigt
(cifs) shareComment	nein	String	Der Kommentar ist beim Browsen des Servers neben dem Namen sichtbar
(cifs) hideUnreadable	nein	false \| true	Alle Dateien und Verzeichnisse, für die der Benutzer keine Lese-Berechtigung hat, sind aus den Verzeichnislisten ausgeblendet
(cifs) enableDFS	nein	false \| true	Für den Share wird ein DFS Eintrag angelegt oder entfernt
(cifs) dfsPath	nein	String, nur Pfadteil subOu\link	Unter diesem Namen wird der DFS Eintrag angelegt: \\d.ethz.ch\groups\subOu
(cifs) domain	nein	D	AD Domain der nachfolgenden Berechtigungsgruppe; immer 'D'
(cifs) groupName	nein	String, AD Gruppenname (ohne Domain)	Die Gruppe erhält einen Eintrag in den 'share permissions' und in der ACL des Filessytems (Permissions), oder wird entfernt (removePermission)
(cifs) access	nein	Allowed
(cifs) permission	nein	Full \| Change \| Read	Berechtigungsstufe bei den 'share permissions'
(nfs) enabled	nein	false \| true	Für den Share wird ein NFS Export angelegt
(nfs) client	nein	Hostname, IP-Adresse , subnet (CIDR Notation) oder netgroup	Der/die benannte/n Client/s erhält/erhalten Zugriff auf den Export (Permissions) oder wird entfernt (removePermission)
(nfs) accessType	nein	RO \| RW	Berechtigungsstufe: Nur-Lesen oder Lese-/Schreibzugriff
(nfs) squash	nein	no_root_squash \| root_squash	Behandlung beim Zugriff auf den Export als Benutzer root: root_squash: die ID für root wird auf die höchste UID gemappt no_root_squash: die ID für root wird auf UID ‘0’ gemappt. Der Benutzer agiert auf dem Share als root.
(nfs) priviledgedPorts	nein	false \| true	Ports < 1024 gelten als privileged und können vom Client nur genutzt werden wenn der Parameter auf 'true' gesetzt wird
(nfs) protocolVersion	nein	v3_sys \| v4_krb5 \| v4_sys_krb5	Regelt das mögliche Zugriffsprotokoll und den Security-Typ für den Client

PUT Example

{
  "name": "phys_astro_experiments",
  "sizeInGB": 2048,
  "inodes": 2048,
  "thresholdInPercent": 90,
  "adminGroup": "ID.CCR.PFM.ALL",
  "snapshotPolicy": "hourlySnapshot",
  "backupPolicy": "noBackup",
  "approvalData": {
    "sapElement": "nnnnn",
    "sapApprover": "new_approver@ethz.ch",
    "approvalReason": "Mehr Platz fuer experimentelle Daten"
   }, 
  "cifsExportData": {
    "removePermission": [
      {
        "domain": "D",
        "groupName": "ID-PPF-NAS-FileShare"
      }
    ],
    "enabled": true,
    "browsable": true,
    "shareComment": "Fileablage fuer experimentelle Daten",
    "hideUnreadable": true,
    "enableDFS": true,
    "dfsPath": "astro\exp",
    "permissions": [
      {
        "domain": "D",
        "groupName": "ID.CCR.PFM.ALL",
        "access": "Allowed",
        "permission": "Change"
      }
    ]
  },
  "nfsExportData": {
    "removePermission": [
      {
        "client": "my-client.ethz.ch"
      }
    ],
    "enabled": true,
    "permissions": [
      {
        "client": "my-new-client.ethz.ch",
        "accessType": "RW",
        "squash": "no_root_squash",
        "priviledgedPorts": false,
        "protocolVersion": "v3_sys"
      }
    ]
  }
}

Setzen eines neuen NAS Share Owners PUT

Beschreibung: Es wird der bestehende Owner des Shares geändert

Bedingungen/Einschränkungen:

Parameter shareName, newOwner und orgUnit müssen zwingend angegeben werden, wobei der neue Owner Mitglied der OrgUnit sein muss
Der angemeldete User muss in der Admingruppe des Shares enthalten sein, um die Änderung ausführen zu können

URL: https://itshopwsvc.ethz.ch:44348/api/nas/newowner

Content-Type: application/json

Syntax und Semantik der einzelnen Parameter im body

Name	Obligatorisch	Syntax	Semantik
shareName	ja	String, beginnend mit orgUnit, danach institute und suffix, jeweils durch Unterstrich getrennt	eindeutiger Name des Shares
newOwner	ja	ETH Username (ohne Domain)	der User wird zum Owner des Shares (Automatisch der Ausführer des Requests, kann aber auch separat gesetzt werden)
orgunit	ja	OuName gem. IT Shop	organisatorische Zugehörigkeit des Shareowners (siehe "user" Property oben)

PUT Example

{
  "shareName": "phys_astro_experiments",
  "newOwner": "mmuster",
  "orgUnit": "ethz"
}

Space shortcuts

Page tree

Allgemeine Information

Authentifizierung

Auslesen der bestehenden NAS Shares GET

Auslesen eines dedizierten NAS Shares GET

Bestellung eines NAS Shares POST

Ändern eines NAS Shares PUT

Setzen eines neuen NAS Share Owners PUT