1HWLOC-GATHER-TOPOLOGY(1)             hwloc            HWLOC-GATHER-TOPOLOGY(1)
2
3
4

NAME

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

SYNOPSIS

10       hwloc-gather-topology [options] <path>
11

OPTIONS

13       --io   Also gather I/O  related  files.   The  gathering  may  be  much
14              slower,  and  the  generated  archive may be much bigger.  --dmi
15              Also gather DMI/SMBIOS related files.   The  gathering  requires
16              root access, and the dmi-sysfs kernel module should be loaded.
17
18       -h --help
19              Display help message and exit
20

DESCRIPTION

22       hwloc-gather-topology saves all the relevant topology files into an ar‐
23       chive (<path>.tar.bz2), the  lstopo  output  (<path>.output),  and  the
24       lstopo   XML   (<path>.xml).    The  utility  for  example  stores  the
25       /proc/cpuinfo file and the entire  /sys/devices/system/node/  directory
26       tree.
27
28       These  files can be used later to explore the machine topology offline.
29       Once the tarball has been extracted, it may for instance  be  given  to
30       some  hwloc command-line utilities through their --input option.  It is
31       also possible to override the default topology that the  hwloc  library
32       will read by setting the extracted path in the HWLOC_FSROOT environment
33       variable.
34
35       The archive and the lstopo textual and XML outputs may also be  submit‐
36       ted to hwloc developers to debug issues remotely.
37
38       hwloc-gather-topology  is a Linux specific tool, it is not installed on
39       other operating systems.
40
41       NOTE: hwloc-gather-topology gathers many  hardware  details  about  the
42       platform.  The outputs and tarball should not be posted on public lists
43       or websites unless it is clear that they contain no sensitive  informa‐
44       tion.
45
46       NOTE:  The  gathering  may  take  several  minutes, especially on large
47       nodes.
48
49       NOTE: It is highly recommended that you read the hwloc(7) overview page
50       before reading this man page.
51

EXAMPLES

53       To store topology information to be used later (possibly on a different
54       host) please run:
55
56            hwloc-gather-topology /tmp/myhost
57
58       It will store all relevant topology files  in  the  /tmp/myhost.tar.bz2
59       archive,  the  lstopo  output  in  the /tmp/myhost.output file, and the
60       lstopo XML in the /tmp/myhost.xml file.  These files can be transferred
61       on another host for later/offline analysis and/or as the input to vari‐
62       ous hwloc utilities.
63
64       To  use  these  data  with  hwloc  utilities   you   have   to   unpack
65       myhost.tar.bz2 archive first:
66
67            tar jxvf /tmp/myhost.tar.bz2
68
69       A new directory named myhost now contains all topology files.  Then you
70       ask various hwloc utilities to use this topology instead of the one  of
71       the  real  machine  by passing --input myhost.  To display the topology
72       just run:
73
74            lstopo --input ./myhost
75
76       It is not necessary that the  topology  is  extracted  in  the  current
77       directory, absolute or relative paths are also supported:
78
79            lstopo --input /path/to/remote/host/extracted/topology/
80
81       To see how hwloc would distribute 8 parallel jobs on the original host:
82
83            hwloc-distrib --input myhost --single 8
84
85       To get the corresponding physical indexes in the previous command:
86
87            hwloc-calc  --input  myhost  --po  --li --proclist $(hwloc-distrib
88       --input myhost --single 8)
89
90       Any program may actually override the default  topology  with  a  given
91       archived  one  even  if  it  does  not  have  a  --input  option.   The
92       HWLOC_FSROOT environment variable should be used to do so:
93
94            HWLOC_FSROOT=myhost hwloc-calc --po --li  --proclist  $(hwloc-dis‐
95       trib --single 8)
96
97       All these commands will produce the same output as if executed directly
98       on the host on which the topology information was  originally  gathered
99       by the hwloc-gather-topology script.
100

RETURN VALUE

102       Upon  successful  execution,  hwloc-gather-topology  will exit with the
103       code 0.
104
105       hwloc-gather-topology will return nonzero exit status if  any  kind  of
106       error  occurs,  such  as (but not limited to) failure to create the ar‐
107       chive or output files.
108

SEE ALSO

110       hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
111
112
113
114
1151.11.12                          Dec 13, 2018         HWLOC-GATHER-TOPOLOGY(1)
Impressum