bionic (1) hwloc-gather-topology.1.gz

NAME

       hwloc-gather-topology  -  Saves  the relevant Linux topology files and the lstopo textual and XML outputs
       for later (possibly offline) usage

SYNOPSIS

       hwloc-gather-topology [options] <path>

OPTIONS

       --io   Also gather I/O related files.  The gathering may be much slower, and the generated archive may be
              much bigger.  --dmi Also gather DMI/SMBIOS related files.  The gathering requires root access, and
              the dmi-sysfs kernel module should be loaded.

       -h --help
              Display help message and exit

DESCRIPTION

       hwloc-gather-topology saves all the relevant topology files into an archive (<path>.tar.bz2), the  lstopo
       output   (<path>.output),  and  the  lstopo  XML  (<path>.xml).   The  utility  for  example  stores  the
       /proc/cpuinfo file and the entire /sys/devices/system/node/ directory tree.

       These files can be used later to explore the  machine  topology  offline.   Once  the  tarball  has  been
       extracted,  it  may  for  instance  be  given  to some hwloc command-line utilities through their --input
       option.  It is also possible to override the default topology that the hwloc library will read by setting
       the extracted path in the HWLOC_FSROOT environment variable.

       The  archive  and  the  lstopo textual and XML outputs may also be submitted to hwloc developers to debug
       issues remotely.

       hwloc-gather-topology is a Linux specific tool, it is not installed on other operating systems.

       NOTE: hwloc-gather-topology gathers many hardware details about the platform.  The  outputs  and  tarball
       should  not  be  posted  on  public  lists  or websites unless it is clear that they contain no sensitive
       information.

       NOTE: It is highly recommended that you read the hwloc(7) overview page before reading this man page.

EXAMPLES

       To store topology information to be used later (possibly on a different host) please run:

            hwloc-gather-topology /tmp/myhost

       It will store all relevant topology files in the /tmp/myhost.tar.bz2 archive, the lstopo  output  in  the
       /tmp/myhost.output  file, and the lstopo XML in the /tmp/myhost.xml file.  These files can be transferred
       on another host for later/offline analysis and/or as the input to various hwloc utilities.

       To use these data with hwloc utilities you have to unpack myhost.tar.bz2 archive first:

            tar jxvf /tmp/myhost.tar.bz2

       A new directory named myhost now contains all topology files.  Then you ask various  hwloc  utilities  to
       use  this  topology  instead  of  the  one of the real machine by passing --input myhost.  To display the
       topology just run:

            lstopo --input ./myhost

       It is not necessary that the topology is extracted in the current directory, absolute or  relative  paths
       are also supported:

            lstopo --input /path/to/remote/host/extracted/topology/

       To see how hwloc would distribute 8 parallel jobs on the original host:

            hwloc-distrib --input myhost --single 8

       To get the corresponding physical indexes in the previous command:

            hwloc-calc --input myhost --po --li --proclist $(hwloc-distrib --input myhost --single 8)

       Any program may actually override the default topology with a given archived one even if it does not have
       a --input option.  The HWLOC_FSROOT environment variable should be used to do so:

            HWLOC_FSROOT=myhost hwloc-calc --po --li --proclist $(hwloc-distrib --single 8)

       All these commands will produce the same output as if executed directly on the host on which the topology
       information was originally gathered by the hwloc-gather-topology script.

RETURN VALUE

       Upon successful execution, hwloc-gather-topology will exit with the code 0.

       hwloc-gather-topology  will  return  nonzero  exit  status  if any kind of error occurs, such as (but not
       limited to) failure to create the archive or output files.

SEE ALSO

       hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)