=head1 SYNOPSIS
- >>> PING "hello"
- <<< 1.0 200 hello
+ <<< PING "hello"
+ >>> 1.0 200 hello
=head1 DESCRIPTION
A typical request/reply cycle looks like:
- >>> PING "hello"
- <<< 1.0 200 hello
+ <<< PING "hello"
+ >>> 1.0 200 hello
In this case the request was the literal string C<"PING \"hello\"\r\n">
(note: followed by carriage return [CR] and line feed [LF]).
The reply was C<"1.0 200 hello\r\n">.
-The E<gt>E<gt>E<gt> and E<lt>E<lt>E<lt> symbols are not part of
+The E<lt>E<lt>E<lt> and E<gt>E<gt>E<gt> symbols are not part of
the protocol. They indicate messages sent to the host and
received from the host respectively.
A few commands return a multi-line response:
- >>> CAPABILITIES
- <<< 1.0 200
- <<< Content-Type: text/xml
- <<< Content-Length: 123
- <<<
- <<< <capabilities>
- <<< <host>
- <<< <cpu>
+ <<< CAPABILITIES
+ >>> 1.0 200
+ >>> Content-Type: text/xml
+ >>> Content-Length: 123
+ >>>
+ >>> <capabilities>
+ >>> <host>
+ >>> <cpu>
(etc.)
The multi-line response consists of headers and blank line and a body,
When a command returns an error, the request / response looks like
this:
- >>> NOSUCHCOMMAND
- <<< 1.0 404 Command not found
+ <<< NOSUCHCOMMAND
+ >>> 1.0 404 Command not found
As in HTTP, C<4xx> and C<5xx> status codes indicate classes of
error. Following the error code is an explanatory string.
case.
The request is always a single line, always consists only of 7 bit
-printable ASCII (apart from the final CRLF), and must be less or equal
-to 4096 characters in length (that includes the final CRLF).
+printable ASCII bytes in the range 32-126 (apart from the final CRLF),
+and must be less or equal to 4096 bytes in length (that includes the
+final CRLF).
Arguments that are strings I<must> be quoted (using double-quotes).
Special characters inside the strings are escaped using backslashes.
-The rules are precisely the same as for C literal strings, so
-for example C<"\t"> is a string containing a single tab character.
+The rules are precisely the same as for C literal strings, so for
+example C<"\t"> is a string containing a single tab character.
-Arguments that are integers appear as integer literals.
+Strings may not contain C<\0> characters in the middle, nor can they
+be NULL.
-Other argument types that are allowed are: booleans (I<true> or
-I<false>).
+Unless specified otherwise, the charset for strings is I<UTF-8>, but
+any bytes outside the range 32-126 must be sent as escape sequences,
+eg. C<"\xC2\xA3"> would encode the pound (currency) sign.
-Note that integers, booleans must never be quoted.
+Arguments that are integers appear as integer literals, with optional
+minus sign (C<->) before. As with C, use a I<0> to indicate octal and
+I<0x> to indicate hexadecimal literals.
+
+Boolean arguments should be sent as I<true> or I<false>.
+
+=head2 AVAILCPUS
+
+ AVAILCPUS
+
+=head3 Returns
+
+Number of available physical cores in the host.
+
+=head3 Example
+
+ <<< AVAILCPUS
+ >>> 1.0 200 4
+
+=head3 Description
+
+Returns the number of physical cores in the host that are available to
+the virtualization system (ie. have not been disabled). See also
+I<PHYSCPUS> which would in almost every case return the same number.
+
+=head2 CORESPERSOCKET
+
+ CORESPERSOCKET
+
+=head3 Returns
+
+Number of cores per socket in the physical host.
+
+=head3 Example
+
+ <<< CORESPERSOCKET
+ >>> 1.0 200 2
+
+=head3 Description
+
+Returns the number of physical cores per socket in the host.
+
+=head2 MEMORY
+
+ MEMORY
+
+=head3 Returns
+
+Amount of memory in host, in kilobytes.
+
+=head3 Example
+
+ <<< MEMORY
+ >>> 1.0 200 2097022
+
+=head3 Description
+
+Returns the total memory in the host, in kilobytes.
+
+=head2 MHZ
+
+ MHZ
+
+=head3 Returns
+
+Speed of host cores in MHz.
+
+=head3 Example
+
+ <<< MHZ
+ >>> 1.0 200 2047
+
+=head3 Description
+
+Returns the clockspeed of host cores in MHz.
+
+=head2 MODEL
+
+ MODEL
+
+=head3 Returns
+
+The host CPU model, a string such as C<i686> or C<x86_64>.
+
+=head3 Example
+
+ <<< MODEL
+ >>> 1.0 200 x86_64
+
+=head3 Description
+
+Returns the host CPU model.
+
+=head2 NODES
+
+ NODES
+
+=head3 Returns
+
+The number of NUMA nodes in the host.
+
+=head3 Example
+
+ <<< NODES
+ >>> 1.0 200 1
+
+=head3 Description
+
+Returns the number of NUMA nodes in the host. If this is 1
+then host memory access is uniform.
+
+=head2 PHYSCPUS
+
+ PHYSCPUS
+
+=head3 Returns
+
+The number of physical cores.
+
+=head3 Example
+
+ <<< PHYSCPUS
+ >>> 1.0 200 4
+
+=head3 Description
+
+Returns the number of physical cores available on the host.
+
+In some (highly unusual) situations, some cores might be
+disabled. To get the number of cores available to do work,
+use C<AVAILCPUS>.
+
+Note that it is common for the guest not to see all of the
+physical CPUs (virtual CPUs E<lt> physical CPUs).
=head2 PING
Returns C<echodata> back to the caller.
+=head3 Example
+
+ <<< PING "hello"
+ >>> 1.0 200 hello
+
=head3 Description
This command is used to test the hostinfo connection.
=item *
-The command succeeds and echos back the same C<echodata> string.
-This indicates that everything is working.
+The command succeeds and echos back the same C<echodata> string. This
+indicates that the connection through to the host daemon is working.
=item *
=back
+=head2 SOCKETSPERNODE
+
+ SOCKETSPERNODE
+
+=head3 Returns
+
+The number of sockets on each node.
+
+=head3 Example
+
+ <<< SOCKETSPERNODE
+ >>> 1.0 200 2
+
+=head3 Description
+
+Returns the number CPU sockets in each NUMA node.
+
+=head2 THREADSPERCORE
+
+ THREADSPERCORE
+
+=head3 Returns
+
+The number of hyperthreads per core.
+
+=head3 Example
+
+ <<< THREADSPERCORE
+ >>> 1.0 200 1
+
+=head3 Description
+
+If hyperthreading is enabled on the host, this returns
+the number of threads on each real core. The numbers
+returned by C<AVAILCPUS> and C<PHYSCPUS> are multiplied
+accordingly.
+
git.annexia.org / virt-hostinfo.git / blobdiff