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

NAME

       hwloc-gather-topology  -  Saves  the relevant Linux and x86 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.

       --dt   Also gather Device-Tree CPU files. These files aren't needed for hwloc, but they may be  used  for
              debugging what Linux exposes in /sys.

       --no-cpuid
              Do not gather x86 CPUID dump using hwloc-gather-cpuid.

       --keep Keep the temporary copy of dumped files instead of destroying it.

       --version
              Report version and exit.

       -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: The gathering may take several minutes, especially on large nodes.

       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-gather-cpuid(1), hwloc-calc(1), hwloc-distrib(1)