General Information
At the moment the API is just accessible for ETHZ employees; students can't use the interface actually.
Authentication
The Webservice uses Basic Authentication of ETHZ AD Domain for authorizing, so you can use your personal ETH user account (including domain).
Example:
Username: mmuster@ethz.ch
Password: xxxxxxx
Get existing NAS shares GET
Description: returns the NAS shares which have been created by authenticated user.
URL: https://itshopwsvc.ethz.ch:44348/api/nas
Get a dedicated NAS share GET
Description: returns the specified NAS share, in case the authenticated user is owner or member of the share's admingroup.
URL: https://itshopwsvc.ethz.ch:44348/api/nas/{sharename}
Ordering NAS share POST
Description: ordering a new NAS share. The authenticated user can order shares for third persons as well.
Constraints:
- name (the sharename pattern requires following information: [ou]_[institute]_[suffix]; be aware that the institute must be affiliated to the OrgUnit)
- approvalData (sapElement & sapApprover must match)
- adminGroup (the user has to be a member of the specified admin group)
URL: https://itshopwsvc.ethz.ch:44348/api/nas
Content-Type: application/json
Syntax and semantic of the body parameters
Name | Mandatory | Syntax | Semantic |
|---|---|---|---|
| name | yes | String, starts with orgUnit, followed by institute and suffix, | defines unique sharename |
| sizeInGB | yes | natural number | size of the Share in GiB |
| inodes | yes | natural number | max amount of files and folders in Share |
| thresholdInPercent | no | 0..100 | threshold in percentage for daily check of occupied size and occupied inodes; when exceeded get notified by email. |
| adminGroup | yes | String, AD groupname (without Domain) | Permission group on the filesystem and in IT Shop (Modification/Deletion) |
| storageClass | yes | QoS1 | |
| location | yes | RZ | HIT | |
| snapshotPolicy | no | dailySnapshot | noSnapshot | Rule for disk-based snapshots |
| backupPolicy | no | dailyBackup | noBackup | Rule for tape-based backup |
| sapElement | yes | 5-digit cost center starting with '2' or 12-digit PSP element incl. hyphen | Billing information |
| sapApprover | yes | Primary e-mail account/ UPN | Billing information |
| approvalReason | no | String | Information for approver, will be shown in Ethis |
| (cifs) enabled | no | false | true | generate CIFS/SMB export for the share |
| (cifs) browsable | no | false | true | the share will be shown in Windows-Explorer while browsing |
| (cifs) shareComment | no | String | visible comment next to the name when browsing |
| (cifs) hideUnreadable | no | false | true | all files and directories which are not permitted for the user are hidden in the folder tree |
| (cifs) enableDFS | no | false | true | creates a DFS entry for the share |
| (cifs) dfsPath | no | String, just part of the path subOu\link | name for the DFS entry: \\d.ethz.ch\groups\subOu\link |
| (cifs) domain | no | D | AD domain; always 'D' |
| (cifs) groupName | no | String, AD group name (without Domain) | the group gets an entry in the 'share permissions' and the ACL of the filessystem |
| (cifs) access | no | Allowed | |
| (cifs) permission | no | Full | Change | Read | Permission level for 'share permission' |
| (nfs) enabled | no | false | true | creates a NFS export for the share |
| (nfs) client | no | Hostname, IP address, subnet (CIDR notation) or netgroup | listed clients get access on the export |
| (nfs) accessType | no | RO | RW | Permission level: only-read or read-/write access |
| (nfs) squash | no | no_root_squash | root_squash | Access on export as root user: root_squash: the ID for root will be mapped on the highest UID no_root_squash: the ID for root will be mapped on UID ‘0’. The user has root privileges on share. |
| (nfs) priviledgedPorts | no | false | true | Ports < 1024 are privileged and can only be used when parameter is 'true' |
| (nfs) protocolVersion | no | v3_sys | v4_krb5 | v4_sys_krb5 | defines access protocol and security type for client |
| user | yes | ETH username (without Domain) | this user will be the owner of the share |
| orgUnit | yes | OuName acc. IT Shop | the user above has to be part of this OU |
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"
}
Modify NAS share PUT
Description: Change configuration of specified NAS share
Constraints:
- Parameter name, user and orgUnit are mandatory
- The user must be owner of the share or member of the admin group
URL: https://itshopwsvc.ethz.ch:44348/api/nas
Content-Type: application/json
Syntax and semantic of the body parameters
Name | Mandatory | Syntax | Semantic |
|---|---|---|---|
| name | yes | String, starting with orgUnit, followed by institute and suffix, | unique sharename |
| sizeInGB | no | natural number | new overall size of the share in GiB |
| inodes | no | natural number | new max amount of files and folders in share |
| thresholdInPercent | no | 0..100 | threshold in percentage for daily check of occupied size and occupied inodes; when exceeded get notified by email. |
| adminGroup | no | String, AD group name (without Domain) | Permission group on the filesystem and in IT Shop (Modification/Deletion) |
| snapshotPolicy | no | dailySnapshot | noSnapshot | new rule for disk-based snapshots |
| backupPolicy | no | dailyBackup | noBackup | new rule for tape-based backup |
| sapElement | no | 5-digit cost center starting with '2' or 12-digit PSP element incl. hyphen | Billing information |
| infomailReceiver | no | Primary e-mail account/ UPN | Billing information |
| approvalReason | no | String | Information for approver, will be shown in Ethis |
| (cifs) enabled | no | false | true | generate or remove CIFS/SMB export for the share |
| (cifs) browsable | no | false | true | the share will be shown in Windows explorer while browsing |
| (cifs) shareComment | no | String | visible comment next to the name when browsing |
| (cifs) hideUnreadable | no | false | true | all files and directories which are not permitted for the user are hidden in the folder tree |
| (cifs) enableDFS | no | false | true | creates a DFS entry for the share |
| (cifs) dfsPath | no | String, part of the path subOu\link | name for the DFS Entry: \\d.ethz.ch\groups\subOu\link |
| (cifs) domain | no | D | AD Domain; always 'D' |
| (cifs) groupName | no | String, AD group name (without domain) | the group gets an entry in the 'share permissions' and the ACL of the filessystem |
| (cifs) access | no | Allowed | |
| (cifs) permission | no | Full | Change | Read | Permission level by 'share permissions' |
| (nfs) enabled | no | false | true | creates a NFS export for the share |
| (nfs) client | no | Hostname, IP address , subnet (CIDR notation) or netgroup | listed clients get access on the export |
| (nfs) accessType | no | RO | RW | Permission level: only-read or read-/write access |
| (nfs) squash | no | no_root_squash | root_squash | Access on export as root user: root_squash: the ID for root will be mapped on the highest UID no_root_squash: the ID for root will be mapped on UID ‘0’. The user has root privileges on share. |
| (nfs) priviledgedPorts | no | false | true | Ports < 1024 are privileged and can only be used when parameter is 'true' |
| (nfs) protocolVersion | no | v3_sys | v4_krb5 | v4_sys_krb5 | defines access protocol and security type for client |
| user | yes | ETH username (without domain) | this user will be checked for owner of the share |
| orgUnit | yes | OuName acc. IT Shop | the user above has to be part of this OU |
PUT Example
{
"name": "phys_astro_experiments",
"sizeInGB": 2048,
"inodes": 2048,
"thresholdInPercent": 90,
"adminGroup": "ID.CCR.PFM.ALL",
"snapshotPolicy": "hourlySnapshot",
"backupPolicy": "noBackup",
"approvalData": {
"sapElement": "nnnnn",
"infomailReceiver": "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"
}
]
},
"user": "mmuster",
"orgUnit": "phys"
}