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)