l3q/l3q.1

.TH L3Q "1" "February 2024" "L3Q client" "User Commands"
.SH NAME
l3q \- l3q client. \fBLight\fR, \fBlight\fR, \fBlight\fRweight \fBqueuing\fR system to run processes/programs in parallell or in sequence on multiple nodes.
.SH SYNOPSIS
.B l3q
\fI[-h] [--version] [-l] {add,show,list,cancel,node,validate} ...\fR
.SH DESCRIPTION
.PP
l3q is the l3q client that sends queries, requests and commands to the l3q daemon \fBl3qd\fR. l3q uses the TCP/IP protocol and all communication with the l3q daemon is handled over network. Client sends POST requests and l3qd responds with json responses. l3q consists of sub-commands that handle different kind of actions, \fBadd\fR adds jobs to l3q, \fBshow\fR prints information of different types, \fBlist\fR prints information in list format, \fBcancel\fR cancels running jobs, \fBnode\fR list status of nodes and changes states on nodes (must be run as root), \fBvalidate\fR to validate client with l3q daemon.
.br
l3q launches \fBjobs\fR that contains one or more \fBtasks\fR on compute \fBnodes\fR.
.br
Before the l3q daemon accepts communication from this client a validation step has to be done first. On the l3q daemon server start the validation daemon and follow the instructions: \fBl3qd --validate-host\fR
.SH QUEUE
The default queueing system in the l3q daemon is similar to a FIFO (first in, first out) stack. The first job that is added will be launched first, if there are more queued jobs they will all be processed in turn from the top. If there are enough resources available for the next queued job to be launch it will be started, until there are no queued jobs left or not enough resources are available. All jobs are processed from top to bottom and when the first queued job will not fit the processing stops, even if there are smaller jobs further down in the queue that would be able to be launched this will not happen. That job has to wait until all previous queued jobs has beed launched first.
.br
Jobs that are in Depend state are not inluded in the queue until dependent jobs are finished.
.SH COMMANDS
.SS "Show commands"
.PP
.TP
\fB\ show [-h] {queue,history,job,status} ... \fR
Shows status and information about nodes and jobs.
.IP
\fB-h\fR, \fB--help\fR show help message and exit
.TP
\fB show status [-h] [-H]\fR
Shows information about all hosts available in l3q.
.IP
\fB-H\fR, \fB--human\fR Prints human-readable output
.br
\fB-h\fR, \fB--help\fR show help message and exit
.TP
\fB show queue [-h] [-l] \fR
Lists all running and queued jobs in l3q.
.br
As a shorthand use: \fBl3q [-l]\fR, this will print the same output.
.IP
\fBColumns in queue\fR:
.br
\fBJobid\fR: l3q id for job
.br
\fBUser\fR: User that added the job
.br
\fBName\fR: Free text to describe job
.br
\fBCores alloc\fR: Number of cores per node that this job is allocating.
.br
\fBNodes alloc\fR: Number of nodes that this job is allocating.
.br
\fBTasks R/T/E:N\fR: Number of tasks: Running/Terminated/Error:Total
.br
\fBState\fR: A job can have the following states: Running, Queued, Terminated, Cancel, Canceled, Error
.br
\fBNodes\fR: Number of nodes that l3q is using for the job.
.IP
\fBAditional columns in queue --long\fR:
.br
\fBInit\fR: Date and time when job was added
.br
\fBStart\fR: Date and time when the job started.
.br
\fBDepend\fR: List all jobs that this job depends on.
.br
\fBNodes\fR: Names of nodes that l3q is using for the job.
.IP
\fB-l\fR, \fB--long\fR  Prints a long and more detailed view of the queue
.br
\fB-h\fR, \fB--help\fR show help message and exit
.TP
\fB show history [-h] [-l] [-n NUMBER] \fR
Lists all terminated and canceled jobs in l3q.
.br
Columns output is equal to process show queue.
.IP
\fB-l\fR, \fB--long\fR Prints a long and more detailed view of the history
.br
\fB-n NUMBER\fR, \fB--number NUMBER\fR Limit the number of old jobs to be displayed.
.TP
\fB show job [-h] [-d] JOBID \fR
Shows information about specified job.
.IP
\fBJOBID\fR Id number of job to show.
.br
\fB-d\fR, \fB--details\fR Shows detailed information about specified job
.br
\fB-h\fR, \fB--help\fR show help message and exit
.TP
\fB show task [-h] TASKID \fR
Shows information about specified task.
.IP
\fBTASKID\fR Id number of task to show.
.br
.br
\fB-h\fR, \fB--help\fR show help message and exit

.SS "List commands"
.PP
.TP
\fB\ list [-h] {task} ... \fR
List different type of info and status of l3q.
.TP
\fB list task [-h] JOBID \fR
List all tasks for specified job.
.IP
\fBJOBID\fR Id number of job to show tasks.
.br
\fB-h\fR, \fB--help\fR show help message and exit

.SS "Add commands"
.PP
.TP
\fB\ add [-h] [-t TASKFILE] [-i] [-d DEPEND] {para,seq} ... \fR
Adds a new job to l3q.
.IP
\fB-t TASKFILE\fR, \fB--taskfile TASKFILE\fR
.br
          Path to file containing all tasks that should be run in sequence or parallel.
.br
          One task per line, empty lines and lines starting with # are ignored.
.br
          TASKFILE must contain special syntax line for either
.br
          parallel or squence job.
.IP
          Special syntax in TASKFILE:
              #--add-para ...
              #--add-seq ...
.br
\fB-i\fR, \fB--jobid\fR
.br
          Jobid of this job will be returned on success as the only output.
.br
          On failure the error message is printed.
.br
\fB-d DEPEND\fR, \fB--depend DEPEND\fR
.br
	     Comma separated list of other jobid that this job depends on.
.br
	     All jobs specified in this joblist have to terminate without
.br
	     errors before this job is started. If a depenedent job fails
.br
	     this job will also fail and will not be started.
.br
	     Example: 1,5,9 (comma separated without whitespaces)
.IP
\fB-h\fR, \fB--help\fR show help message and exit
.TP
\fB add para [-h] [-c CORES] [-n NODES] [-j JOBNAME] [-i] [-d DEPEND] TASKFILE \fR
Adds a new parallel job of single threaded tasks to l3q.
.br
Number of tasks executed in parallel depends on number of cores and hosts specified.
.IP
\fBTASKFILE\fR   Path to file containing all tasks that should be run in parallel.
.br
           One task per line, empty lines and lines starting with # are ignored.
.br
           Lines containing tasks must have one or two column, first column
.br
           specifies a path to an executable program and the second optional
.br
           column contains working directory. Columns are separated by
.br
           whitespace. If second column, workdir, is not specified,
.br
           users home directory will be used as default workdir.
.br
\fB-c CORES\fR, \fB--cores CORES\fR
.br
           Number of cores to use on each node, --nodes is also required.
\fB-n NODES\fR, \fB--nodes NODES\fR
.br
           Number of nodes to use, L3Q will choose which nodes to use. --cores is also required.
\fB-j JOBNAME\fR, \fB--jobname JOBNAME\fR
.br
           Name of specifed job.
.br
\fB-i\fR, \fB--jobid\fR
.br
           Jobid of this job will be returned on success as the only output.
.br
           On failure the error message is printed.
.br
\fB-d DEPEND\fR, \fB--depend DEPEND\fR
.br
	      Comma separated list of other jobid that this job depends on.
.br
	      All jobs specified in this joblist have to terminate without
.br
	      errors before this job is started. If a depenedent job fails
.br
	      this job will also fail and will not be started.
.br
	      Example: 1,5,9 (comma separated without whitespaces)
.br
\fB-h\fR, \fB--help\fR show help message and exit
.IP
If TASKFILE only contains one task on each line then both options --cores and --nodes are required.
.br
If TASKFILE contains a line with the special syntax specifying required options then no options are required on the command line.
.br
If TASKFILE contains the special syntax line and --core and --nodes are given as arguments these options will be used
.br
and the special syntax line will be ignored.
.IP
Special syntax in TASKFILE:
.br
#--add-para --cores 5 --nodes 8
.TP
\fB add seq [-h] [-j JOBNAME] [-i] [-d DEPEND] TASKFILE \fR
Adds a new sequential job of single threaded tasks to l3q.
.br
All tasks will be executed one after another.
.IP
\fBTASKFILE\fR   Path to file containing all tasks that should be run in parallel.
.br
           One task per line, empty lines and lines starting with # are ignored.
.br
           Lines containing tasks must have one or two column, first column
.br
           specifies a path to an executable program and the second optional
.br
           column contains working directory. Columns are separated by
.br
           whitespace. If second column, workdir, is not specified,
.br
           users home directory will be used as default workdir.
.br
\fB-j JOBNAME\fR, \fB--jobname JOBNAME\fR
.br
           Name of specifed job.
.br
\fB-i\fR, \fB--jobid\fR
.br
           Jobid of this job will be returned on success as the only output.
.br
           On failure the error message is printed.
.br
\fB-d DEPEND\fR, \fB--depend DEPEND\fR
.br
	      Comma separated list of other jobid that this job depends on.
.br
	      All jobs specified in this joblist have to terminate without
.br
	      errors before this job is started. If a depenedent job fails
.br
	      this job will also fail and will not be started.
.br
	      Example: 1,5,9 (comma separated without whitespaces)
.br
\fB-h\fR, \fB--help\fR show help message and exit
.IP
If TASKFILE contains a line with the special syntax specifying the name of the task this name will be used.
.br
If TASKFILE contains the special syntax line and --jobname is given as arguments this options will be used
.br
and the special syntax line will be ignored.
.br
If TASKFILE contains multiple special syntax lines the last line will be used.
.IP
Special syntax in TASKFILE:
.br
#--add-seq --jobname The name of the job

.SS "Cancel commands"
.PP
.TP
\fB\ cancel [-h] {job} ... \fR
\fB-h\fR, \fB--help\fR show help message and exit
.TP
\fB cancel job [-h] JOBID \fR
Cancel specified running or queued job.
.IP
\fBJOBID\fR Id number of job to cancel
.br
\fB-h\fR, \fB--help\fR show help message and exit
.SS "Node commands"
.PP
.TP
\fB\ node [-h] {set} \fR
Configure compute nodes in L3Q
.IP
\fB-h\fR, \fB--help\fR show help message and exit
.TP
\fB\ node set [-h] [--online] [--offline] NODENAME \fR
Set status of a compute node in L3Q.
.br
If set offline current running processes will run 
until finished before set offline and will not 
accept any new processes.
.IP
\fBNODENAME\fR Name of node to change state on in the L3Q daemon.
.br
\fB--online\fR Set node soft online and will display Soft Online
.br
         until node is reacheble from L3Q daemon and changes to Online,
.br
         if node is not reachable L3Q daemon will set node offline again.
.br
\fB--offline\fR Set node offline,
.br
          if node still run processes, these will finish before
.br	  
          set in Maintenance mode and Maintenance draining mode will show in status.
.br
          While in Maitenance mode the node will not run any new jobs.
.br
\fB-h\fR, \fB--help\fR show help message and exit
.SS "Validate commands"
.PP
.TP
\fB validate [-h] -p PORT \fR
Configure and validate client with daemon.
.br
Without validation the clients on this host will not be able to communicate with daemon.
.br
Start the validation server on the same server as the l3q daemon with:
.br
l3qd --validate-host
.br
and follow instructions.
.IP
\fB-p PORT\fR, \fB--port PORT\fR Port that the validate server is listening on.
.br
\fB-h\fR, \fB--help\fR show help message and exit
.SH FILES
/etc/l3q/l3q.conf
.br
/etc/l3q/network.l3q
.br
/var/log/l3q/l3q-client.log
.SH AUTHOR
Written by Marcus Pedersén
.SH "REPORTING BUGS"
<https://notabug.org/marcux/l3q>
.SH COPYRIGHT
Copyright \(co 2023 Marcus Pedersén
.br
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH "SEE ALSO"
l3q.conf(5)