lshosts

Displays hosts and their static resource information.

Synopsis

lshosts [-w | -l] [-cname] [-a] [-R res_req] [-T] [host_name ... | host_group ... | cluster_name ... ]
lshosts [-cname] [-a] [-R res_req] [-o "field_name[:[-][output_width][:unit] ... [delimiter='character']"] [-json] [host_name | host_group | cluster_name] ...
lshosts [-cname] [-a] [-loc] -s|-sl [static_resource_name ...]
lshosts -gpu [-mig] [-w] [-cname] [-a] [-R res_req] [host_name | host_group | cluster_name] ...
lshosts [-h | -V]

Description

By default, returns the following information: host name, host type, host model, CPU factor, number of CPUs, total memory, total swap space, whether the host is a server host, and static resources. Exclusive resources are prefixed with an exclamation mark (!). Displays information about all hosts in the cluster.

In the IBM® Spectrum LSF multicluster capability job forwarding model, the default behavior is to return the following information: host name, host type, host model, CPU factor, number of CPUs, total memory, total swap space, whether the host is a server host, and static resources. Displays information about all hosts in the local cluster and for all hosts in equivalent remote clusters that the local cluster sees.

In the IBM Spectrum LSF multicluster capability resource leasing model, returns information about hosts in the local cluster.

The -s option displays information about the static resources (shared or host-based) and their associated hosts.

Options

-a
Dynamic cluster only. Shows information about all hosts, including Dynamic cluster virtual machine hosts configured with the jobvm resource. Default output includes only standard LSF hosts and Dynamic cluster hosts configured with the dchost resource.
-cname
In LSF Advanced Edition, includes the cluster name for execution cluster hosts and host groups in output.
Note: This command option is deprecated and might be removed in a future version of LSF.
-gpu
Displays GPU topology information for the cluster.
-json

Displays the customized output in JSON format.

When specified, lshosts -o displays the customized output in the JSON format.

This option applies only to output for the lshosts -o command for customized output. This option has no effect when used with lshosts without the -o option and the LSF_LSHOSTS_FORMAT environment variable and parameter are not defined.

-l
Displays host information in a long multi-line format. In addition to the default fields, displays additional information, including maximum /tmp space, the number of local disks, the execution priority for remote jobs, load thresholds, and run windows.
-mig
Displays detailed information on Nvidia Multi-Instance GPU (MIG) instances. This option must be specified with the -gpu option.
-w
Displays host information in wide format. Fields are displayed without truncation.
-o

Sets the customized output format.

  • Specify which lshosts fields (or aliases instead of the full field names), in which order, and with what width to display.
  • Specify only the lshosts field name or alias to set its output to unlimited width and left justification.
  • Specify the colon (:) without a width to set the output width to the recommended width for that field.
  • Specify the colon (:) with a width to set the maximum number of characters to display for the field. When its value exceeds this width, lshosts truncates the ending characters.
  • Specify a hyphen (-) to set right justification when lshosts displays the output for the specific field. If not specified, the default is to set left justification when lshosts displays the output for a field.
  • Specify the unit colon (:) with a unit to set the unit for the output of the specific field:
    • Specify S to use a built-in conversion for space or capacity, such as memory or disk space. Values are automatically scaled for M (MB), G (GB), and T (TB), where the default unit is M (MB).
      For example, when displaying the mem field with a specified width of 3,
      • For a value of 30, running the lshosts -o "maxmem:3:S" command shows 30.0M.
      • For a value of 4096, running the lshosts -o "maxswp:3:S" command shows 4.0G.
      • For a value of 5000000, running the lshosts -o "maxtmp:3:S" command shows 4.8T.
    • Specify D to use a built-in conversion for duration or time, such as memory or disk space. Values are automatically scaled for s (seconds), m (minutes), h (hours), and d (days), where the default unit is s (seconds). The automatically scaled value is rounded up after the first decimal point.
      For example, when displaying the external mytime resource field with a specified width of 5,
      • For a value of 30, running the lshosts -o "mytime:5:D" command shows 30.0s.
      • For a value of 8000, running the lshosts -o "mytime:5:D" command shows 2.2h.
      • For a value of 5000000, running the lshosts -o "mytime:5:D" command shows 57.8d.
    • Specify any other string of 1 - 3 characters and the characters are used as is in the field value. The first character must be a letter (upper or lower case). The second and third characters must be an alphanumeric character.

      For example, when displaying the external gpu_temp resource with a width of 3, running the lshosts -o "gpu_temp:3:C" command for a value of 30 shows 30C

  • Use delimiter= to set the delimiting character to display between different headers and fields. This delimiter must be a single character. By default, the delimiter is a space.
Output customization applies only to the output for certain lshosts options:
  • LSF_LSHOSTS_FORMAT and lshosts -o both apply to output for the lshosts command with no options, and for lshosts options with output that filter information, including the following options: -a, -cname.
  • LSF_LSHOSTS_FORMAT and lshosts -o do not apply to output for other lshosts options that use a modified format, including the following options: -l, -w.

The lshosts -o option overrides the LSF_LSHOSTS_FORMAT environment variable, which overrides the LSF_LSHOSTS_FORMAT setting in lsf.conf.

The following are the field names used to specify the lshosts fields to display, recommended width, aliases you can use instead of field names, and units of measurement for the displayed field:

Table 1. Output fields for lshosts
Field name Width Aliases Unit
HOST_NAME 20 hname  
type 10    
model 10    
cpuf 10    
ncpus 8    
maxmem 10   LSF_UNIT_FOR_LIMITS in lsf.conf (KB by default)
maxswp 10   LSF_UNIT_FOR_LIMITS in lsf.conf (KB by default)
server 10    
RESOURCES 20 res  
ndisks 8    
maxtmp 10   LSF_UNIT_FOR_LIMITS in lsf.conf (KB by default)
rexpri 10    
nprocs 8    
ncores 8    
nthreads 10    
RUN_WINDOWS 20 runwin  

Field names and aliases are not case-sensitive. Valid values for the output width are any positive integer 1 - 4096.

For example: 
lshosts -o "HOST_NAME type: RESOURCES:- RUN_WINDOWS:-16 delimiter='^'"

This command displays the following fields:

  • HOST_NAME with unlimited width and left-aligned.
  • type with a maximum width of 10 characters (which is the recommended width) and left-aligned.
  • RESOURCES with a maximum width of 20 characters (which is the recommended width) and right-aligned.
  • RUN_WINDOWS with a maximum width of 16 characters and right-aligned.
  • The ^ character is displayed between different headers and fields.
-R res_req
Displays only information about the hosts that satisfy the resource requirement expression. LSF supports ordering of resource requirements on all load indices, including external load indices, either static or dynamic.

In the IBM Spectrum LSF multicluster capability, displays only information about the hosts in the local cluster that satisfy the resource requirement expression.

host_name ... | host_group ... | cluster_name ...
Displays only information about the specified hosts, host groups, or clusters.

To display host group information, the LSF_HOSTGROUP_INFO=Y setting must be specified in the lsf.conf file. Do not use quotation marks when you specify multiple hosts, host groups, or a combination.

For the IBM Spectrum LSF multicluster capability, displays information about hosts in the specified clusters. The names of the hosts that belong to the cluster are displayed instead of the name of the cluster. Do not use quotation marks when you specify multiple clusters.

-s | -sl [static_resource_name ...] [-loc]
Displays information about the specified resources. The resources must be static resources (shared or host-based). If you do not specify a specific resource name, then displays information about all resources.

Returns the resource name (such as fpga), the amount of these resources (such as 3), and the resource locations (by hostname), if you use the-s option .

As of Fix Pack 14, specifying the -sl option returns same resource information as the -s option, with the addition of names assigned to each resource (for example, the fpga resource could be assigned three names: card1, card2, and card3).

Note that of the LOCATION parameter in the lsf.cluster.cluster_name file is set to all to indicate that the resource is shared by all hosts in the cluster, the LOCATION field in the lshosts -s command output also displays ALL. To display the individual names of all the hosts in the cluster in the lshosts -s command output, specify the -loc option together with the -s option.

-h
Prints command usage to stderr and exits.
-T
Displays host topology information for each host or cluster.
-V
Prints the LSF release version to stderr and exits.

Host-based default output

HOST_NAME
The name of the host. This display field is truncated.
type
The host type. This display field is truncated.

With the IBM Spectrum LSF multicluster capability, if the host type of a host in the remote cluster is not defined in the local cluster, the keyword unknown is displayed.

model
The host model. This display field is truncated.

With the IBM Spectrum LSF multicluster capability, if the host model of a host in the remote cluster is not defined in the local cluster, the keyword unknown is displayed.

cpuf
The relative CPU performance factor. The CPU factor is used to scale the CPU load value so that differences in CPU speeds are considered. The faster the CPU, the larger the CPU factor.

The default CPU factor of a host with an unknown host type is 1.0.

ncpus
The number of processors on this host.

If the LSF_ENABLE_DUALCORE=Y parameter is specified in the lsf.conf file for multi-core CPU hosts, displays the number of cores instead of physical CPUs.

If EGO is enabled in the LSF cluster and the EGO_DEFINE_NCPUS parameter is specified in the lsf.conf or ego.conf file, the appropriate value for ncpus is displayed, depending on the value of the EGO_DEFINE_NCPUS parameter:
EGO_DEFINE_NCPUS=procs
ncpus=number of processors.
EGO_DEFINE_NCPUS=cores
ncpus=number of processors × number of cores per processor.
EGO_DEFINE_NCPUS=threads
ncpus=number of processors × number of cores per processor × number of threads per core.
Note: The EGO_DEFINE_NCPUS=cores parameter is the same as setting the LSF_ENABLE_DUALCORE=Y parameter.
nprocs
The number of physical processors per CPU configured on a host.
ncores
The number of cores per processor that is configured on a host.
nthreads
The number of threads per core that is configured on a host.
maxmem
The maximum amount of physical memory available for user processes.

By default, the amount is displayed in KB. The amount can appear in MB depending on the actual system memory. Use the LSF_UNIT_FOR_LIMITS parameter in the lsf.conf file to specify a larger unit for the limit (GB, TB, PB, or EB).

maxswp
The total available swap space.

By default, the amount is displayed in KB. The amount can appear in MB depending on the actual system swap space. Use the LSF_UNIT_FOR_LIMITS parameter in the lsf.conf file to specify a larger unit for the limit (GB, TB, PB, or EB).

For the Solaris operating system, the swap space is virtual, a layer between anonymous memory pages and the physical storage (or disk-backed swap space). Virtual swap space on Solaris systems is equal to the sum of all its physical (disk-backed) swap space plus a portion of the currently available physical memory, which might be a dynamic value.

server
Indicates whether the host is a server or client host. Yes is displayed for LSF servers. No is displayed for LSF clients. Dyn is displayed for dynamic hosts.
RESOURCES
The Boolean resources that are defined for this host, denoted by resource names, and the values of external numeric and string static resources. External static resources are configured in the lsf.cluster and lsf.shared files.

Host-based -l option output

ndisks
The number of local disk drives directly attached to the host.
maxtmp
The maximum /tmp space in MB configured on a host.
rexpri
UNIX only. The execution priority of remote jobs that are run by the RES. rexpri is a number between -20 and 20, with -20 representing the highest priority and 20 the lowest. The default rexpri is 0, which corresponds to the default scheduling priority of 0 on BSD-based UNIX systems and 20 on System V-based systems.
nprocs
The number of physical processors per CPU configured on a host.
ncores
The number of cores per processor that is configured on a host.
nthreads
The number of threads per core that is configured on a host.
RUN_WINDOWS
The time windows during which LIM considers the host as available to run remote jobs. These run windows have the same function for LSF hosts as dispatch windows have for LSF hosts.
LOAD_THRESHOLDS
The thresholds for scheduling interactive jobs. If a load index exceeds the load threshold (or falls below the load threshold, for decreasing load indices), the host status is changed to busy. If the threshold is displayed as a dash -, the value of that load index does not affect the host status.
HARDWARE TOPOLOGY
NUMA and socket information for the host.
AVAILABLE CPU FREQUENCY
Shows the available CPU frequencies for the host. Used for energy aware scheduling.
CURRENT CPU FREQUENCY (GHz)
Shows the current CPU frequencies that are selected for the host and the number of CPUs on the host. Used for energy aware scheduling.

Resource-based output -s or -sl option

Displays the static resources (shared or host-based). Each line gives the value and the associated hosts for the static resource. Static shared resources are configured in the lsf.shared and lsf.cluster files.

The following fields are displayed:
RESOURCE
A description of the resource; for example, an FPGA device could be identified as fpga.
VALUE
The numeric value of the static resource; that is the amount of available units of the resource (for example, 3).
LOCATION
The hostname that are associated with the static resource.
NAMES
(As of Fix Pack 14) Names assigned to the different types of the resource, each separated by a space; for example card1 card2 card3 are possible options for the fpga resource.

Topology-based output -T option

Displays host topology information for each host or cluster. Topology is displayed by processor unit level: NUMA node, if present, socket, core, and thread. A socket is a collection of cores with a direct pipe to memory. Each socket contains 1 or more cores. The topology display does not necessarily refer to a physical socket, but rather to the memory architecture of the machine. A core is a single entity capable of performing computations. On hosts with hyper-threading enabled, a core can contain one or more threads.

The following fields are displayed:
Host[memory] host_name
Maximum memory available on the host followed by the host name. If memory availability cannot be determined, a dash (-) is displayed for the host.

For hosts that do not support affinity scheduling, a dash (-) is displayed for host memory and no host topology is displayed.

NUMA[numa_node: max_mem]
Maximum NUMA node memory. It is possible for requested memory for the NUMA node to be greater than the maximum available memory displayed.

If no NUMA nodes are present, then the NUMA layer in the output is not shown. Other relevant items such as host, socket, core, and thread are still shown.

If the host is not available, only the host name is displayed. A dash (-) is shown where available host memory would normally be displayed.

The lshosts -T output differs from the bhosts -aff output:
  • Socket and core IDs are not displayed for each NUMA node.
  • The requested memory of a NUMA node is not displayed
  • lshosts -T displays all enabled CPUs on a host, not just the CPUs defined in the CPU list in lsb.hosts
In the following example, full topology (NUMA, socket, and core) information is shown for hostA. Hosts hostB and hostC are either not NUMA hosts or they are not available:
lshosts -T
Host[15.7G] hostA
    NUMA[0: 15.7G]
        Socket
            core(0)
        Socket
            core(1)
        Socket
            core(2)
        Socket
            core(3)
        Socket
            core(4)
        Socket
            core(5)
        Socket
            core(6)
        Socket
            core(7)

Host[-] hostB

Host[-] hostC
When LSF cannot detect processor unit topology, the lshosts -T command displays processor units to the closest level. 
lshosts -T
     Host[1009M] hostA 
            Socket (0 1)

hostA has two processor units: 0 and 1. LSF cannot detect core information, so the processor unit is attached to the socket level.

Hardware topology information is not shown for client hosts and hosts in a mixed cluster or IBM Spectrum LSF multicluster capability environment that is running a version of LSF that is earlier than Version 9.1.

Output: GPU-based -gpu option

The -gpu option displays information of the GPUs on the host.

The following fields are displayed:
HOST_NAME
The host name.
gpu_id
The GPU IDs on the host. Each GPU is shown as a separate line.
gpu_model
The full model name, which consists of the GPU brand name and the model type.
gpu_driver
The full version of the GPU driver.
gpu_factor
The GPU run time weighting factor.
numa_id
The NUMA node ID.
vendor
The GPU vendor type (that is, the GPU brand name).
mig
Flag to indicate whether the GPU supports Nvidia Multi-Instance GPU (MIG) functions.
If the -mig option is specified with the -gpu option, shows the following detailed MIG instances information:
devid
The MIG device (instance) ID.
gid
The GPU instance ID.
cid
The compute instance ID.
inst_name
The MIG instance name.

Files

Reads lsf.cluster.cluster_name.

See also

ls_info, ls_policy, ls_gethostinfo, lsf.shared