agpubox command reference

agpubox agpubox drop block agpubox free block agpubox gentoken block agpubox glog block agpubox gpus block agpubox gsconfig block agpubox help block agpubox list block agpubox listdevices block agpubox listgpu block agpubox listprocess block agpubox listserver block agpubox maint block agpubox olog block agpubox osconfig block agpubox ping block agpubox rprocess block agpubox status block agpubox token block agpubox udrop block agpubox udrop block agpubox version block agpubox whoami block -q -n -v

Global switches:
-q Quiet. Display only the crucial information.
-v Verbose. The most detailed data will be displayed during command execution.
-n Disable coloring where applicable (for example the agpubox lg subcommand output)

agpubox drop

Description: Removing the GPUs from the infrastructure.

agpubox drop block
drop d ID start_ID - end_ID ,

Parameters:
ID Remove the GPU with the specified General ID
start_ID Beginning of the range of GPUs that will be dropped
end_ID End of the range of GPUs that will be dropped

Examples:
Remove the GPU with GID 3 from the infrastructure:
$ agpubox drop 3
Remove the GPUs with GIDs 4 and 9 from the infrastructure:
$ agpubox drop 4,9
Remove the GPUs with GIDs 1, from 4 to 9, from 11 to 13 and 3:
$ agpubox drop 1,4-9,11-13,3

GPU can be removed from infrastructure only if there are no users connected to it. To drop GPUs on behalf of a particular user, administrator can use subcommand agpubox udrop.

agpubox drop operation is irreversible! In order to return GPUs removed this way, GPUServers must be restarted.

agpubox free

Description: Displaying all GPUs in the infrastructure ready for allocations.

agpubox free block
free f

Example
Display list of free GPUs in the infrastructure:
$ agpubox free
+-------+-----------------------------------+---------------+---------------+
|DID     |GPU name                          |Memory (GB)    |Available GPU  |
+-------+-----------------------------------+---------------+---------------+
|1      |GeForce GTX 690                    |2              |8              |
|2      |GeForce GTX 680                    |2              |15             |
|3      |GeForce GTX 780                    |3              |9              |
+-------+-----------------------------------+---------------+---------------+

Displayed table:

Column name Description
DID Device ID indicating type of GPU that can be allocated.
GPU name Name of free GPU device.
Memory (GB) GPU memory expressed in gigabytes.
Available GPU Number of free GPUs of particular type.

agpubox gpus

Description: Listing all GPUs connected to OServer.

agpubox gpus block
gpus g

Example:
List all GPUs from the OServer:
$ agpubox gpus
+---+------------------+---------------+-----------+-----------+-----+-----------+
|GID|GPU name          |PCI            |GPUServer  |Status     |Users|Since      |
+---+------------------+---------------+-----------+-----------+-----+-----------+
|6  |GeForce GTX 690   |710C:04:00.0   |GPU12      |SHARED     |1    |2013-12-18 |
|7  |GeForce GTX 690   |710C:07:00.0   |GPU12      |SHARED     |1    |2013-12-18 |
|8  |GeForce GTX 690   |710F:08:00.0   |GPU15      |OFF        |1    |2013-12-18 |
|9  |GeForce GTX 690   |7111:03:00.0   |GPU17      |EXCLUSIVE  |1    |2013-12-18 |
|10 |GeForce GTX 690   |7111:04:00.0   |GPU17      |SHARED     |1    |2013-12-18 |
|11 |GeForce GTX 690   |7111:07:00.0   |GPU17      |EXCLUSIVE  |1    |2013-12-18 |
|.. |..                |...            |...        |...        |...  |...        |

Displayed table:

Column name Description
GID General identification number of GPU generated automatically when GPUServer connects to OServer. General ID is used for administrator’s operations on GPU. GID is never shown to user using gpubox command.
GPU name Name of GPU device.
PCI PCI address format <domain>:<bus>:<slot>.<function> where:
<domain> is 4 characters long and consists of hexadecimal values of the two last octets of the GPUServer’s IP address. For example: the domain in the PCI address for the GPUServer with the 203.0.113.12 IP address will be 710C because 113 converted to HEX is 0x71, and 12 is 0xC.
<bus>:<slot>.<function> is taken from lspci command on GPUServer.
GPUServer The name of the GPUServer on which a particular GPU is installed.
Status Status of a particular GPU. Can be one of the following: EXCLUSIVE, SHARED, OFF, FREE, STOPPED or BROKEN
Users Number of users that allocated the GPU.
Since Timestamp indicating when the GPU was added to the infrastructure. Format: YYYY-MM-DD hh:mm:ss

agpubox glog

Description: Displaying log from GPUServer.

agpubox glog block
glog gl gpuserver_name --severity -s = all trace debug info notice warning error critical --limit -l = -100 number_of_entries --begindate -b = "YYYY-MM-DD hh:mm:ss" --enddate -e = "YYYY-MM-DD hh:mm:ss"

Parameters:
gpuserver_name Name of the GPUServer.
--severity|s=<severity> Display log with severity. Default value: all.
--limit|-l=<number_of_entries> Display specified number of entries from GPUServer’s log. A positive value of the parameter means that the first messages of the log are displayed at the specified number. When the value is negative, the last messages are to be displayed.
Default value: -100

A limit cannot be applied when both --begindate and --enddate parameters are used.

If used with --begindate, then number_of_entries must be a positive number.
If used with --enddate, then number_of_entries must be a negative number.

--begindate|-b=<"YYYY-MM-DD hh:mm:ss"> Set the date and time of the first message to be displayed. This information must be given in the following format: "YYYY-MM-DD hh:mm:ss"
--enddate|-e=<"YYYY-MM-DD hh:mm:ss"> Set the date and time of the last message to be displayed. This information must be given in the following format: "YYYY-MM-DD hh:mm:ss"

Examples:
Display log from GPUServer GPU11 with default limit -100 last messages and severity all:
$ agpubox glog GPU11
Display the first 500 log entries from GPUServer GPU15 applying default severity all:
$ agpubox glog GPU15 --limit=500
Display the last 250 log entries from GPUServer GPU12 applying default severity all:
$ agpubox gl GPU12 -l=-250
Display the last 100 messages (default limit) from GPUServer GPU13 applying severity warning:
$ agpubox glog GPU13 -s=warning
Display the last 1000 messages from GPUServer GPU15 applying severity info:
$ agpubox gl GPU15 --limit=-1000 --severity=info
Display the last 100 messages (default limit) from GPUServer GPU14 that appeared after 2013-12-20 15:00:00 applying default severity all:
$ agpubox gl GPU14 -e="2013-12-20 15:00:00"
Display the last 200 messages from GPUServer GPU13 that appeared before 2013-12-20 13:20:00 applying default severity all:
$ agpubox gl GPU13 --enddate="2013-12-20 13:20:00" -l=-200
Display the messages from GPUServer GPU11 with severity "trace" that appeared between 2013-12-20 11:30:00 and 2013-12-20 18:00:00:
$ agpubox glog GPU11 -s=trace -b="2013-12-20 11:30:00" -e="2013-12-20 18:00:00"

agpubox ping

Description: Checking connection with the OServer.

agpubox ping block
ping i OServer_address

Parameters:
OServer_address Full HTTP/HTTPS address of the OServer

Examples:
Ping OServer with address https://203.0.113.1:8082:
$ agpubox ping https://203.0.113.1:8082

agpubox list

Description: Listing of the GPU allocations.

agpubox list block
list l userid

Parameters:
userid Display allocations only for a chosen user.

Examples:
List all of the allocations in the infrastructure:
$ agpubox list
+---+---+-------+------------+--------------------+-------------+--------------+---------+---------+--------------------+
|GID|LID|UserID |User name   |GPU name            |PCI          |Client's IP   |GPUServer|Status   |Since               |
+---+---+-------+------------+--------------------+-------------+--------------+---------+---------+--------------------+
|6  |1  |bob    |Bob         |GeForce GTX 780     |710B:04:00.0 |203.0.113.150 |GPU11    |SHARED   |2013-12-22 11:44:52 |
|7  |2  |bob    |Bob         |GeForce GTX 680     |710B:07:00.0 |203.0.113.150 |GPU11    |SHARED   |2013-12-22 11:41:16 |
|8  |1  |mary   |Mary        |GeForce GTX 690     |7112:08:00.0 |203.0.113.152 |GPU18    |EXCLUSIVE|2013-12-22 11:40:56 |
|8  |1  |john   |John        |GeForce GTX 690     |7112:07:00.0 |203.0.113.155 |GPU18    |SHARED   |2013-12-22 11:41:05 |
|...|...|...    |...         |...                 |...          |...           |...      |...      |...                 |
List the allocations for John:
$ agpubox list john
+---+---+-------+------------+--------------------+-------------+--------------+---------+-------+--------------------+
|GID|LID|UserID |User name   |GPU name            |PCI          |Client's IP   |GPUServer|Status |Since               |
+---+---+-------+------------+--------------------+-------------+--------------+---------+-------+--------------------+
|8  |1  |john   |John        |GeForce GTX 690     |7112:07:00.0 |203.0.113.155 |GPU18    |SHARED |2013-12-22 11:41:05 |
+---+---+-------+------------+--------------------+-------------+--------------+---------+-------+--------------------+

Displayed table:

Column name Description
GID General identification number of the GPU generates automatically when the GPUServer connects with the OServer. General ID is used for the administrators’ operations on the GPUs. The GID is never shown to the user using the gpubox command.
LID Local ID of the GPU visible to the user in the gpubox list command.
UserID Basic user indicator.
User name Supplementary user indicator which, for example, can be the name and surname of a user.
GPU name The name of the GPU device.
PCI PCI address format <domain>:<bus>:<slot>.<function> where:
<domain> is 4 characters long and consists of hexadecimal values of the two last octets of the GPUServer’s IP address. For example: the domain in the PCI address for the GPUServer with the 203.0.113.12 IP address will be 710C because 113 hexadecimally is 0x71, and 12 is 0xC.
<bus>:<slot>.<function> is taken from lspci command on GPUServer.
Client's IP The IP address of the Client’s machine that is used for the GPU allocation.
GPUServer The name of the GPUServer on which the GPU is installed.
Status The status of a particular GPU. It can be one of the following: EXCLUSIVE, SHARED, OFF, FREE, STOPPED or BROKEN.
Since Timestamp indicating when the GPU was allocated. Format: YYYY-MM-DD hh:mm:ss

agpubox listdevices

Description: Listing of the device types and number of the GPUs in the infrastructure.

agpubox listdevices block
listdevices ld

Examples:
List of device types:
$ agpubox ld
+----+----------------+---------------+-------+----------------+
|DID |GPU name        |Memory (GB)    |Status |Number of GPUs  |
+----+----------------+---------------+-------+----------------+
|1   |GeForce GTX 690 |2              |FREE   |4               |
|1   |GeForce GTX 690 |2              |SHARED |8               |
|2   |GeForce GTX 680 |2              |SHARED |12              |
|3   |GeForce GTX 780 |3              |SHARED |9               |
+----+----------------+---------------+-------+----------------+

Displayed table:

Column name Description
DID The identification number of the GPU device type.
GPU name The name of the GPU device.
Memory (GB) GPU memory expressed in gigabytes.
Status The status of a particular GPU. It can be one of the following: EXCLUSIVE, SHARED, OFF, FREE, STOPPED or BROKEN.
Number of GPUs The number of GPUs of a particular type and status in the infrastructure.

agpubox listgpu

Description: Monitoring the GPUs.

agpubox listgpu block
listgpu lg gpuserver_name

Parameters:
gpuserver_name List the GPUs only from a chosen GPUServer.

Examples:
List details for all the GPUs in the infrastructure:
$ agpubox lg
+----+---------+------+---------------+---------+-------------+--------+-----------+----------------+------------+
|GID |GPUServer|Device|GPU name       |Temp. (C)|Fan speed (%)|Util (%)|Mem (MB)   |Free mem (MB)   |Kernel limit|
+----+---------+------+---------------+---------+-------------+--------+-----------+----------------+------------+
|17  |GPU10    |0     |GeForce GTX 690|47       |34           |0       |2047       |1968            |no          |
|6   |GPU10    |1     |GeForce GTX 690|57       |41           |0       |2047       |1826            |no          |
|7   |GPU10    |2     |GeForce GTX 690|62       |44           |0       |2047       |1828            |yes         |
|8   |GPU10    |3     |GeForce GTX 690|55       |39           |0       |2047       |1830            |no          |
|9   |GPU11    |0     |GeForce GTX 680|41       |30           |0       |2047       |1974            |no          |
|10  |GPU11    |1     |GeForce GTX 680|42       |30           |0       |2047       |1975            |no          |
|... |...      |...   |...            |...      |...          |0       |...        |...             |...         |
List details for the GPUs from the GPUServer GPU10:
$ agpubox listgpu GPU10
+----+---------+------+---------------+---------+-------------+--------+-----------+----------------+------------+
|GID |GPUServer|Device|GPU name       |Temp. (C)|Fan speed (%)|Util (%)|Mem (MB)   |Free mem (MB)   |Kernel limit|
+----+---------+------+---------------+---------+-------------+--------+-----------+----------------+------------+
|17  |GPU10    |0     |GeForce GTX 690|47       |34           |0       |2047       |1968            |no          |
|6   |GPU10    |1     |GeForce GTX 690|57       |41           |0       |2047       |1826            |no          |
|7   |GPU10    |2     |GeForce GTX 690|62       |44           |0       |2047       |1828            |yes         |
|8   |GPU10    |3     |GeForce GTX 690|55       |39           |0       |2047       |1830            |no          |
+----+---------+------+---------------+---------+-------------+--------+-----------+----------------+------------+

Displayed table:

Column name Description
GID The general identification number of the GPU generates automatically when the GPUServer connects with the OServer. General ID is used for the administrators’ operations on the GPU. The GID is never shown to the user using the gpubox command.
GPUServer The name of the GPUServer on which a particular GPU is installed.
Device The ordinal number of the device.
GPU name The name of the GPU device.
Temp. (C) The temperature of the GPU expressed in degrees Celsius.
Fan speed (%) The speed of the GPU fan rotation expressed in maximum speed percentage.
Util (%) The utilization of the GPU expressed in percentage. If monitoring of this value is not supported by a particular GPU, only zeroes will be displayed.

Utilization of GPU will be correctly displayed only for professional Tesla and Quadro cards from the Fermi and Kepler families.

Memory (MB) Total GPU memory expressed in megabytes.
Free memory (MB) Currently free GPU memory expressed in megabytes.
Kernel limit The GPU property regarding kernel termination while using the graphical user interface. If the column value is yes, it means that for this particular GPU, the driver will terminate kernels that exceed the specified timespan in order to keep the GUI responsive.

agpubox listprocess

Description: Listing processes active on the GPUServers.

agpubox listprocess block
listprocess lp gpuserver_name

Parameters:
gpuserver_name List processes only from the chosen GPUServer.

Examples:
Display processes running on the GPUServers:
$ agpubox lp
+---------+------+------+----------+------+-------+--------------+----+----+-----+-------+--------+-----+-------+-------+---+
|GPUServer|Type  |UserID|PID       |Active|Since  |Client's IP   |Net |Rtn |Rtn/s|Rx     |Rx/s    |Tx   |Tx/s   |Mem    |Dev|
+---------+------+------+----------+------+-------+--------------+----+----+-----+-------+--------+-----+-------+-------+---+
|GPU14    |main  |john  |10677     |yes   |2013...|203.0.103.155 |TCP |44  |0    |47.7MB |0B/s    |592B |0B/s   |487.9MB|0  |
|GPU14    |thread|john  |10677     |yes   |2013...|203.0.103.155 |IB  |7.0K|721  |266.8KB|13.8KB/s|3.7MB|8.8KB/s|487.9MB|3  |
|GPU11    |thread|mary  |30010     |yes   |2013...|203.0.103.152 |IB  |4.4K|617  |212.2KB|11.5KB/s|4.1MB|7.5KB/s|943.9MB|1  |
|...      |...   |...   |...       |...   |...    |...           |... |... |...  |...    |...     |...  |...    |...    |...|
Display processes running on the GPUServer GPU14:
$ agpubox listprocess GPU14
+---------+------+------+----------+------+-------+--------------+----+----+-----+-------+--------+-----+-------+-------+---+
|GPUServer|Type  |UserID|PID       |Active|Since  |Client's IP   |Net |Rtn |Rtn/s|Rx     |Rx/s    |Tx   |Tx/s   |Mem    |Dev|
+---------+------+------+----------+------+-------+--------------+----+----+-----+-------+--------+-----+-------+-------+---+
|GPU14    |main  |john  |10677     |yes   |2013...|203.0.103.155 |TCP |44  |0    |47.7MB |0B/s    |592B |0B/s   |487.9MB|0  |
|GPU14    |thread|john  |10677     |yes   |2013...|203.0.103.155 |IB  |7.0K|721  |266.8KB|13.8KB/s|3.7MB|8.8KB/s|487.9MB|3  |
+---------+------+------+----------+------+-------+--------------+----+----+-----+-------+--------+-----+-------+-------+---+

Displayed table:

Column name Description
GPUServer The name of the GPUServer on which a particular process is run.
Type Process type (either main or thread).
UserID The user who launched a particular process.
PID Process ID on the GPUServer.
Active Can be yes or no and indicates if the process is active on the GPUServer.
Since Timestamp indicating when the process started. Format: YYYY-MM-DD hh:mm:ss
Client's IP The IP address of the Client that started the process.
Network Network type: IB as InfiniBand or TCP as TCP/IP communication
Rtn Routines count.
Rx Data received.
Rx/s Data received per second.
Tx Data transmitted.
Tx/s Data transmitted per second.
Mem(MB) GPU memory used by the process.
Dev The ordinal number of the device.

The main process is always displayed as the TCP and system shows the GPUServer's origin system.

agpubox listserver

Description: Listing GPUServers.

agpubox listserver block
listserver ls gpuserver_name

Parameters:
gpuserver_name Display only the details of the chosen GPUServer.

Example:
List the GPUServers in the infrastructure:
$ agpubox listserver
+---------+-------+-----------+------------+-----+--------------------+--------+
|         |Number |Number of  |            |     |                    |        |
|GPUServer|of GPUs|Allocations|IP          |Port |Since               |Version |
+---------+-------+-----------+------------+-----+--------------------+--------+
|GPU11    |4      |4          |203.0.103.11|9393 |2013-12-23 07:06:11 |0.8     |
|GPU12    |4      |4          |203.0.103.12|9393 |2013-12-23 07:06:08 |0.8     |
|GPU13    |4      |4          |203.0.103.13|9393 |2013-12-23 07:06:10 |0.8     |
|...      |...    |...        |...         |...  |...                 |...     |

Displayed table:

Column name Description
GPUServer The name of the GPUServer.
Number of GPUs The number of GPUs installed on particular GPUServer.
Number of allocations Total number of allocations from particular GPUServer.
IP GPUServer’s IP address
Port Bind port used by Client to connect to GPUServer
Since Timestamp indicating when the GPUServer became active. Format: YYYY-MM-DD hh:mm:ss
Version GPUBox GPUServer version installed.

agpubox osconfig

Description: Displaying and changing the OServer's configuration.

agpubox osconfig block
osconfig oc config_parameter value

Parameters:
config_parameter OServer parameter from configuration file.
value The new value of the specified parameter. If not given, then the current value will be displayed.

Examples:
Display values of read-only and read-write parameters for OServer configuration:
$ agpubox osconfig
Display the value of parameter oserver_log_level:
$ agpubox oc oserver_log_level
Change the value of parameter oserver_max_gpu_per_user to 10:
$ agpubox osconfig oserver_max_gpu_per_user 10
Change the value of parameter oserver_log_level to INFO:
$ agpubox oc oserver_log_level INFO

agpubox passwd

Description: Changing password.

agpubox passwd block
passwd p

Example:
Change my password from passwd1 to passwd2:
$ agpubox passwd
Please enter your current password: ******* (type:passwd1)
Enter the new password: ******* (type: passwd2)
Retype the new password: ******* (retype: passwd2)
Password changed

Administrators can use subcommands agpubox passwd and gpubox passwd interchangeably.

agpubox gsconfig

Description: Displaying and changing GPUServers' configuration.

agpubox gsconfig block
gsconfig gc gpuserver_name config_parameter value

Parameters:
gpuserver_name The name of the GPUServer
config_parameter GPUServer parameter from the configuration file.
value The new value of the specified parameter. If not given, then the current value will be displayed.

Examples:
Display values of read-only and read-write parameters for GPUServer GPU12:
$ agpubox gsconfig GPU12
Display the value of parameter gpuserver_infiniband_enabled on GPUServer GPU12:
$ agpubox gc GPU12 gpuserver_infiniband_enabled
Change the value of parameter gpuserver_log_level to TRACE on GPUServer GPU12:
$ agpubox gsconfig GPU12 gpuserver_log_level TRACE

agpubox olog

Description: Displaying the log from OServer.

agpubox olog block
olog ol --severity -s = all trace debug info notice warning error critical --limit -l = -100 number_of_entries --begindate -b = "YYYY-MM-DD hh:mm:ss" --enddate -e = "YYYY-MM-DD hh:mm:ss"

Parameters:
--severity|s=<severity> Display log with severity. Default value: all.
--limit|-l=<number_of_entries> Displays specified number of entries from the OServer’s log. A positive value of the parameter means that the first log messages are displayed at a specified number. When the value of the parameter is negative, the last messages will be displayed.
Default value: -100

A limit cannot be applied when both the --begindate and --enddate parameters are used.

If used with --begindate, then the number_of_entries must be a positive number.
If used with --enddate, then the number_of_entries must be a negative number.

--begindate|-b=<"YYYY-MM-DD hh:mm:ss"> Set the date and time of the first message to be displayed. That information must be given in the following format: "YYYY-MM-DD hh:mm:ss"
--enddate|-e=<"YYYY-MM-DD hh:mm:ss"> Set the date and time of the last message to be displayed. That information must be given in the following format: "YYYY-MM-DD hh:mm:ss"

Examples:
Display the log from the OServer with the default -100 last messages and severity all:
$ agpubox olog
Display the first 1000 OServer log entries with default severity all:
$ agpubox ol --limit=1000
Display the last 200 OServer log entries with severity notice:
$ agpubox olog --severity=notice --limit=-200
Display the default -100 last OServer log entries with severity all before 2013-12-26 13:05:30:
$ agpubox ol --enddate="2013-12-26 13:05:30"
Display all messages with severity <critical> that appeared between 2013-12-26 12:00:00 and 2013-12-29 12:00:00
$ agpubox olog -b="2013-12-26 12:00:00" -e="2013-12-29 12:00:00" -s=critical
Display the last 400 OServer log entries with default severity all of those that appeared before 2013-12-29 12:00:00:
$ agpubox ol -l=-400 -e="2013-12-29 12:00:00"

agpubox gentoken

Description: Generating a new token for the current or chosen user.

agpubox gentoken block
gentoken gt --userid -u = userid --yes -y --no -n

Parameters:
--userid|-u Generate a new token for the user with a specified userid
--yes|-y Automatically confirm overwriting of the file.
--no|-n Automatically deny overwriting of the file.

Examples:
Generate a new token for my account:
$ agpubox gentoken
Configuration file /home/bob/.gpubox already exists, overwrite it? [y/n]y
Generate a new token for user john:
$ agpubox gt john

When using agpubox gentoken for a current account, a new token is generated, regardless of the user's decision whether or not to overwrite the existing Client's configuration file or not. If a new configuration file is not downloaded, the Client will not be able to perform any operations until the user downloads a new configuration file using gpubox token command.

Generating a token for another user will leave him unable to use the Client until he downloads a new token using gpubox token subcommand.

Applying the agpubox gentoken subcommand will result in dropping the current superuser's allocations.

Generating a new token on behalf of another user using the agpubox gentoken subcommand with parameter --userid|-u=<user_id> will remove every GPU allocation done by the indicated user.

agpubox maint

Description: Maintenance of corrupted allocations or Monitor1 data.

agpubox maint block
maint m orphans o mon1offload m1o --begindate -b = "YYYY-DD-MM hh:mm:ss" --enddate -e = "YYYY-DD-MM hh:mm:ss" mon1delete m1d --dateto -d = "YYYY-MM-DD hh:mm:ss" now

Parameters:
orphans|o When the connection with the GPUServer is lost and cannot be recovered, users’ allocations related to this GPUServer become orphans. Using this parameter for maint subcommand removes all corrupted allocation records from the database.
mon1offload|m1o Offload Monitor1 data to file: {oserver_datafiles_path}/monitor1/m1_{start-time}_{end-time} where {oserver_datafiles_path} is parameter in OServer configuration.
Optionally, the range of the offload can be specified with timestamps indicated by the --begindate|-b and --enddate|-e parameters.
mon1delete|m1d Delete all data from Monitor1 up to the timestamp YYYY-MM-DD hh:mm:ss specified in the required --dateto|-d parameter. To delete data that appeared up to the moment of executing the command, the value now can be used for the --dateto|-d parameter

The orphan maintenance process also removes records regarding the GPUs in the 'BROKEN' and 'STOPPED' usage status.


Examples:
Perform the maintenance of corrupted allocations:
$ agpubox maint orphans
Offload Monitor1 data to file:
$ agpubox m mon1offload

agpubox rprocess

Description: Removing inactive processes from GPUServers.

agpubox rprocess block
rprocess rp gpuserver_name process_id

Parameters:
gpuserver_name The name of the GPUServer.
process_id The ID of an inactive process that is displayed in agpubox listprocess.

Example:

Remove inactive processes with id 30221 from GPUServer GPU15:
agpubox rp GPU14 30221

agpubox status

Description: Displaying and changing GPUs' status.

agpubox status block
status s gpu_id off free shared exclusive

Parameters:
gpu_id GPU’s Global ID
off GPU is unavailable for new allocations.
free GPU is free for new allocations.
shared GPU works in shared mode and can be simultaneously used by a number of different users, as indicated by oserver_max_users_per_gpu parameter .
exclusive GPU works in exclusive mode and can be used by a single user.

Examples:
Display statuses of GPUs in the infrastructure:
$ agpubox status
+----+----------------+------------+---------+---------+-----+--------------------+
|GID |GPU name        |PCI         |GPUServer|Status   |Users|Since               |
+----+----------------+------------+---------+---------+-----+--------------------+
|1   |GeForce GTX 680 |710A:03:00.0|GPU10    |EXCLUSIVE|1    |2013-12-19 08:06:08 |
|2   |GeForce GTX 680 |710A:04:00.0|GPU10    |SHARED   |3    |2013-12-19 08:06:08 |
|3   |GeForce GTX 780 |710A:07:00.0|GPU10    |SHARED   |2    |2013-12-19 08:06:08 |
|4   |GeForce GTX 780 |710A:08:00.0|GPU10    |SHARED   |5    |2013-12-19 08:06:08 |
|5   |GeForce GTX 690 |710C:03:00.0|GPU12    |SHARED   |2    |2013-12-19 08:06:10 |
|6   |GeForce GTX 690 |710C:04:00.0|GPU12    |FREE     |0    |2013-12-19 08:06:10 |
|... |...             |...         |...      |...      |...  |...                 |
Change the status of GPU with GID 1 to SHARED:
$ agpubox status 1 shared
Change the status of GPU with GID 6 to OFF:
$ agpubox s 6 off
Check the status of GPU with GID 26:
$ agpubox s 26

Changing status can be done immediately, but only when the chosen GPU is used by:
0 users when changing to FREE or OFF
0 or 1 users when changing to SHARED or EXCLUSIVE

In other cases, change will be marked as PENDING until the required circumstances occur.

Displayed table:

Column name Description
GID The general identification number of GPU is generated automatically when GPUServer connects to the OServer. General ID is used for the administrators’ operations on GPU. GID is never shown to the user using gpubox command.
GPU name Name of GPU device.
PCI PCI address format <domain>:<bus>:<slot>.<function> where:
<domain> is 4 characters long and consists of hexadecimal values of the two last octets of the GPUServer’s IP address. For example: the domain in the PCI address for the GPUServer with the 203.0.113.12 IP address will be 710C because 113 converted to HEX is 0x71, and 12 is 0xC.
<bus>:<slot>.<function> is taken from lspci command on GPUServer.
GPUServer The name of the GPUServer on which a particular GPU is installed.
Status Status of particular GPU. Can be one of the following: EXCLUSIVE, SHARED, OFF, FREE, STOPPED or BROKEN.
Users The number of users using a particular GPU.
Since Timestamp indicating when the GPU became active. Format: YYYY-MM-DD hh:mm:ss

agpubox token

Description: Logging in by downloading a user's token.

agpubox token block
token t --user -u = user_id --oserver -o = OServer_address --yes -y --password -p = password

Parameters::
--user|-u=<user_id> user_id of the account to log in.
--oserver|-o=<OServer_address> Full HTTP/HTTPS address to OServer
--yes|-y Confirm the file overwrite automatically.
--password|-p=<password> Password to the user's account. If not given, then the user will be asked to enter it.

Example:
Download a token for the user bob on OServer http://203.0.103.1:8081 using password passwd1
$ agpubox t -u=bob --oserver=http://203.0.103.1:8081
Enter password: ******* (type: passwd1)
Configuration file /home/bob/.gpubox already exists, overwrite it? [y/n]y
Login successful.

Administrators can use subcommands agpubox token and gpubox token interchangeably.

agpubox udrop

Description: Dropping GPUs on behalf of another user.

agpubox udrop block
udrop u user_id all gpu_id

Parameters:
user_id userid of the user that allocated GPUs
all Drop all of the GPUs allocated to the indicated user
gpu_id Global ID of GPU that will be removed from user’s allocations.

Examples:
Drop GPU with GID 5 on behalf of user mary:
$ agpubox udrop mary 5
Drop all GPUs that are allocated to user john:
$ agpubox ud john all

agpubox user

Description: Managing users.

agpubox user block
user u agpubox user --add block agpubox user --delete block agpubox user --list block agpubox user --modify block

agpubox user --add

Description: Adding new user.

agpubox user --add block
--add -a --userid -u = user_id --username n = username --password -p = password

Parameters:
--userid|-u=<user_id> Basic user indicator. UserID must be at least 5 characters long, may contain only alphanumeric characters and is case-sensitive. First character must be a letter.
--username|-n Supplementary user indicator. Username must be at least 5 characters long, may contain spaces, alphanumeric characters and is case-sensitive. First character must be a letter.
--password|-p When not given you will prompted to enter password. Password can contain any printable ASCII characters, is case sensitive and must be at least 6 characters long.

Examples:
Add user with userid anne username Anne Smith and password passwd1
$ agpubox user --add -u=anne -n="Anne Smith"
Enter the password: ******* (type: passwd1)
Retype password: ******* (retype: passwd1)
Created
Add user with userid jack username Jack Johnson and password passwd2
$ agpubox u -a --userid=jack --username="Jack Johnson" -p=passwd2

agpubox user --delete

Description: Deleting existing user.

agpubox user --delete block
--delete -d --userid -u = user_id --yes -y

Parameters:
--userid|-u=<user_id> UserID of user that is to be deleted.
--yes|-y Automatically confirm deleting the user.

Example:
Delete user with userid jack:
$ agpubox u -d -u=jack

Only yes confirms deleting user. y, Y, YES and so on are not read as a confirmation.

agpubox user --list

Description: Listing users.

agpubox user --list block
--list -l --userid -u = user_id

Parameters:
--userid|-u=<user_id> List only data regarding a specified user.

Examples:
Display list of all users in the infrastructure:
$ agpubox user -l
+------+-------+-----------+-------+-------+-----------+-----------+-----+-------------+-----------+
|UserID|GroupID|Username   |Enabled|Max GPU|Valid from |Valid to   |Tries|Success login|Fail login |
+------+-------+-----------+-------+-------+-----------+-----------+-----+-------------+-----------+
|bob   |0      |Bob Jones  |yes    |16     |2013-12-...|2999-12-...|0    |2013-12-...  |0001-01-...|
|mary  |1      |Mary Smith |no     |30     |2013-12-...|2999-12-...|5    |2013-12-...  |0001-01-...|
|john  |1      |John Miller|yes    |0      |2013-12-...|2999-12-...|0    |2013-12-...  |0001-01-...|
+------+-------+-----------+-------+-------+-----------+-----------+-----+-------------+-----------+
Display details of user john:
$ agpubox u --list -u=john

To zeroize user's failed password attempts, the administrator has to enable him again using --enable|-e parameter in agpubox user --modify subcommand.

Displayed table:

Column name Description
UserID Basic user indicator.
GroupID Group to which user is assigned. Can be either 0 (administrator) or 1 (user).
Username Supplementary user indicator (i.e. name and surname).
Enabled Information about whether user’s account is enabled (yes) or disabled (no).
Max GPU Maximum number of GPUs that can be allocated by user.
Valid from Timestamp indicating from when user’s account is active.
Valid to Timestamp indicating to when user’s account is active.
Tries Number of failed login attempts. After 5th failed attempt the account is automatically disabled.
Successful login Timestamp of last successful login. Format: YYYY-MM-DD hh:mm:ss
Failed login Timestamp of last failed login attempt. Format: YYYY-MM-DD hh:mm:ss

agpubox user --modify

Description: Modifying user.

agpubox user --modify block
--modify -m --userid -u = user_id --enable -e --disable -d --username -n = username --group -g = 1 0 --password -p = group_id --comment -c = comment --maxgpu -x = max_gpu_number --validto -t = "YYYY-MM-DD hh:mm:ss" --validfrom -f = "YYYY-MM-DD hh:mm:ss"

Parameters:
--userid|-u=<user_id> UserID of user for whom new settings are to be applied.
--enable|-e Enable user.
--disable|-d Disable user.
--username|-n=<username> Define the new username. If the new username contains spaces it must be given in quotation marks.
--group|-g=<1|0> Assign user either to group 0 (with administrator’s credentials) or 1 (regular user).
--password|-p=[password] Change user’s password. If new password is not given after the parameter, administrator will be prompted to enter it after executing command.
--comment|-c=<comment> Give a comment regarding user. If contains spaces the comment must be given in quotation marks.

To see comments an administrator can use agpubox user --list in verbose mode (-v parameter).

Combined parameters are not running in transaction and part of the subcommand can finish with success.

--maxgpu|-x=<max_gpu_number> Set maximum number of GPUs that a user can allocate. 0 means unlimited.
--validfrom|-f=<'YYYY-MM-DD hh:mm:ss'> The timestamp from when the user’s account is valid.
--validto|-t=<'YYYY-MM-DD hh:mm:ss'> The timestamp to when the user’s account is valid.

Parameters --enable and --disable are mutually exclusive.


Examples:
Enable user mary:
$ agpubox u --modify --userid=mary --enable
Enable user mary and change her Max GPU limit to 40:
$ agpubox u -m -u=mary -e -x=40
Set user's john Valid from timestamp to 2013-01-10 00:00:00 and set his Max GPU limit ot 0 (unlimited):
$ agpubox u -m -u=john -t="2013-01-10 00:00:00" -x=0
Add comment "Extremely good 3D artist!" to user mary:
$ agpubox user -m -u=mary -c="Extremely good 3D artist!"
Assign user john to group 0 (administrators):
$ agpubox u -m -u=john -g=0

agpubox version

Description: Displaying installed version of GPUBox Client.

agpubox version block
version v

Example:
Display my GPUBox Client version:
$ agpubox v

agpubox whoami

Description: Displaying information about currently used account.

agpubox whoami block
whoami w
Show my administrator account's details:
$ agpubox whoami

agpubox whoami displays more detailed information than gpubox whoami

agpubox help

Description: Displaying help for chosen subcommand.

agpubox help block
help ? config c drop d free f glog gl ping i listdevices ld listgpu lg listprocess lp listserver ls osconfig oc gentoken gt maint m rprocess rp status s token t udrop ud user u version v whoami w
Display help for agpubox user subcommand:
$ agpubox help user
Display help for agpubox status subcommand:
$ agpubox ? status