add file portalclients.md

82652174 · Jan Siwiec · c33cd66a · 82652174
Commit 82652174 authored 7 months ago by Jan Siwiec
--- a/docs.it4i/general/tools/portal-clients.md
+++ b/docs.it4i/general/tools/portal-clients.md
+# it4i-portal-clients
+
+it4i-portal-clients provides simple user-friendly shell interface
+to call [IT4I API](https://docs.it4i.cz/apiv1/) requests and display their respond.
+
+!!! important
+
+	Python 2.7 is required.
+
+Limits are placed on the number of requests you may make to [IT4I API](https://docs.it4i.cz/apiv1/).
+Rate limit can be changed without any warning at any time, but the default is **6 requests per minute**.
+Exceeding the limit will lead to your IP address being temporarily blocked from making further requests.
+The block will automatically be lifted by waiting an hour.
+
+## List of Available Utilities
+
+* [it4icheckaccess](#it4icheckaccess) - Shows if IT4I account and/or related project has the access to specified cluster and queue.
+* [it4idedicatedtime](#it4idedicatedtime) - Shows IT4I dedicated time.
+* [it4ifree](#it4ifree) - Shows some basic information from IT4I PBS accounting.
+* [it4ifsusage](#it4ifsusage) - Shows filesystem usage of IT4I cluster storage systems.
+* [it4iuserfsusage](#it4iuserfsusage) - Shows user filesystem usage of IT4I cluster storage systems.
+* [it4projectifsusage](#it4iprojectfsusage) - Shows project filesystem usage of IT4I cluster storage systems.
+* [it4imotd](#it4imotd) - Shows IT4I messages of the day into formatted text or HTML page (using TAL / Zope Page Template).
+
+## Installation/Upgrading
+
+```bash
+pip install --upgrade it4i.portal.clients
+```
+
+## Sample Configuration File main.cfg
+
+```bash
+[main]
+
+# IT4I API
+api_url = https://scs.it4i.cz/api/v1/
+it4ifreetoken = <your_token>
+```
+
+Username is taken from OS, therefore the script has to be run under the same user login name as you use to log into clusters.
+
+* System-wide config file path: ```/usr/local/etc/it4i-portal-clients/main.cfg```
+* Local user's config file path: ```~/.it4ifree```
+
+## it4icheckaccess
+
+### Help of IT4ICHECKACCESS
+
+```console
+$ it4icheckaccess -h
+usage: it4icheckaccess [-h] -l LOGIN -c CLUSTER -q QUEUE [-p PROJECT]
+
+The command shows if an IT4I account and/or related project has the access to
+specified cluster and queue. Return exit code 99 if access is not granted.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -l LOGIN, --login LOGIN
+                        user login
+  -c CLUSTER, --cluster CLUSTER
+                        cluster name
+  -q QUEUE, --queue QUEUE
+                        queue
+  -p PROJECT, --project PROJECT
+                        project id
+```
+
+### Example of IT4ICHECKACCESS
+
+```console
+$ it4icheckaccess -l xxx0123 -c barbora -q qcpu_exp -p DD-12-345
+OK Access granted for regular queue.
+```
+
+## it4idedicatedtime
+
+### Help of IT4IDEDICATEDTIME
+
+```console
+$ it4idedicatedtime -h
+usage: it4idedicatedtime [-h] [-m {active,planned}]
+                         [-c {barbora,karolina}]
+
+The command shows IT4I dedicated time. By default all planned and active
+outages of all clusters are displayed. Return exit code 99 if there is no
+outage, otherwise return 0.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -m {active,planned}, --message {active,planned}
+                        select type of dedicated time. Planned contains also
+                        active
+  -c {barbora,karolina}, --cluster {barbora,karolina}
+                        select cluster
+```
+
+### Example of IT4IDEDICATEDTIME
+
+```console
+$ it4idedicatedtime
+Cluster    Start                End                  Last update
+---------  -------------------  -------------------  -------------------
+barbora    2024-03-19 08:00:00  2024-03-19 09:30:00  2024-03-08 08:24:33
+karolina   2024-03-19 08:00:00  2024-03-19 09:30:00  2024-03-08 08:23:40
+```
+
+## it4ifree
+
+### Help of IT4IFREE
+
+```console
+$ it4ifree -h
+usage: it4ifree [-h] [-p] [-a]
+
+The command shows some basic information from IT4I SLURM accounting. The
+data is related to the current user and to all projects in which user
+participates.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -p, --percent
+                        show values in percentage. Projects with unlimited resources are not displayed
+  -a, --all             Show all resources include inactive and future ones.
+
+
+Columns of "Projects I am participating in":
+         PID: Project ID/account string.
+        Type: Standard or multiyear project.
+   Days left: Days till the given project expires.
+       Total: Core-hours allocated to the given project.
+        Used: Sum of core-hours used by all project members.
+          My: Core-hours used by the current user only.
+        Free: Core-hours that haven't yet been utilized.
+
+Columns of "Projects I am Primarily Investigating" (if present):
+         PID: Project ID/account string.
+        Type: Standard or multiyear project.
+       Login: Project member's login name.
+        Used: Project member's used core-hours.
+```
+
+### Example of IT4IFREE
+
+```console
+$ it4ifree
+
+Projects I am participating in
+==============================
+PID         Resource type    Days left      Total     Used      By me     Free
+----------  ---------------  -------------  --------  --------  --------  --------
+OPEN-XX-XX  Karolina GPU      249                42         0         0        42
+            Barbora CPU       249                42         5         5        37
+            Legacy NCH        249               100         0         0       100
+
+
+Projects I am Primarily Investigating
+=====================================
+PID         Resource type    Login      Usage
+----------  --------------   -------  --------
+OPEN-XX-XX  Barbora CPU      user1          3
+            Barbora CPU      user2          2
+            Karolina GPU     N/A            0
+            Legacy NCH       N/A            0
+
+
+Legend
+======
+N/A   =    No one used this resource yet
+Legacy Normalized core hours are in NCH
+Everything else is in Node Hours
+```
+
+## it4ifsusage
+
+### Help of IT4IFSUSAGE
+
+```console
+$ it4ifsusage -h
+usage: it4ifsusage [-h]
+
+The command shows filesystem usage of IT4I cluster storage systems
+
+optional arguments:
+  -h, --help            show this help message and exit
+```
+
+### Example of IT4IFSUSAGE
+
+```console
+$ it4ifsusage
+Quota Type     Cluster / PID    File System    Space used    Space limit    Entries used    Entries limit    Last update
+-------------  ---------------  -------------  ------------  -------------  --------------  ---------------  -------------------
+User           barbora          /home          2.9 GB        25.0 GB        183             500,000          2024-03-22 16:50:10
+User           karolina         /home          3.0 MB        25.0 GB        150             500,000          2024-03-22 17:00:07
+User           barbora          /scratch       0 Bytes       10.0 TB        0               10,000,000       2024-03-22 16:50:28
+User           karolina         /scratch       0 Bytes       0 Bytes        0               0                2024-03-22 17:00:43
+Project        service          proj3          1.5 TB        1.0 TB         169,933         198,000          2024-03-22 17:00:02
+```
+
+## it4iuserfsusage
+
+### Help of IT4IUSERFSUSAGE
+
+```console
+$ it4iuserfsusage -h
+usage: it4iuserfsusage [-h] [-c {all,barbora, karolina}]
+
+The command shows user filesystem usage of IT4I cluster storage systems
+
+optional arguments:
+  -h, --help            show this help message and exit
+```
+
+### Example of IT4IUSERFSUSAGE
+
+```console
+$ it4iuserfsusage
+Cluster          File System    Space used    Space limit      Entries used  Entries limit    Last update
+---------------  -------------  ------------  -------------  --------------  ---------------  -------------------
+barbora          /home          2.9  GB       25.0 GB                   183  500,000          2024-03-22 16:50:10
+karolina         /home          3.0 MB        25.0 GB                   150  500,000          2024-03-22 17:00:07
+barbora          /scratch       0 Bytes       10.0 TB                     0  10,000,000       2024-03-22 16:50:28
+karolina         /scratch       0 Bytes       0 Bytes                     0  0                2024-03-22 17:00:43
+```
+
+## it4iprojectfsusage
+
+### Help of IT4IPROJECTFSUSAGE
+
+```console
+$ it4iprojectfsusage -h
+usage: it4iprojectfsusage [-h] [-p {PID, all}]
+
+The command shows project filesystem usage of IT4I cluster storage systems
+
+optional arguments:
+  -h, --help            show this help message and exit
+```
+
+### Example of IT4IPROJECTFSUSAGE
+
+```console
+$ it4iprojectfsusage
+PID              File System    Space used    Space limit      Entries used  Entries limit    Last update
+---------------  -------------  ------------  -------------  --------------  ---------------  -------------------
+service          proj3          3.1 GB        1.0 TB                      5  100,000          2024-03-22 17:00:02
+it4i-x-y         proj1          3.1 TB        2.0 TB                      5  100,000          2024-03-22 17:00:02
+dd-13-5          proj3          2 GB          3.0 TB                      5  100,000          2024-03-22 17:00:02
+projectx         proj2          150 TB        4.0 TB                      5  100,000          2024-03-22 17:00:02
+```
+
+## it4imotd
+
+### Help of IT4IMOTD
+
+```console
+$ it4imotd -h
+usage: it4imotd [-h] [-t TEMPLATE] [-w WIDTH] [-c]
+
+The command shows IT4I messages of the day into formatted text or HTML page.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -t TEMPLATE, --template TEMPLATE
+                        path to TAL / Zope Page Template, output will be
+                        formatted into HTML page
+  -w WIDTH, --width WIDTH
+                        maximum line width (intended for text rendering,
+                        default of 78 columns)
+  -c, --cron            sleep from 10 up to 60 seconds prior to any actions
+  -m {TYPE}, --message {TYPE}
+                        select type of messages
+                        supported types:
+                            all,
+                            public-service-announcement,
+                            service-recovered-up,
+                            critical-service-down,
+                            service-hard-down,
+                            auxiliary-service-down,
+                            planned-outage,
+                            service-degraded,
+                            important,
+                            notice.
+```
+
+### Example of IT4IMOTD
+
+```console
+$ it4imotd
+
+                       Message of the Day (DD/MM/YYYY)
+                            (YYYY-MM-DD hh:mm:ss)
+
+More on https://...
+```