Hostinfo day 6: RPM packaging, initscripts, hostinfo-status, hostinfo-test.

[virt-hostinfo.git] / hostinfod / hostinfo.pod

diff --git a/hostinfod/hostinfo.pod b/hostinfod/hostinfo.pod
index 0f700eb..6ddfe57 100644 (file)
--- a/hostinfod/hostinfo.pod
+++ b/hostinfod/hostinfo.pod
@@ -31,19 +31,21 @@ The system administrator (of the host) must:
 
 =item *
 
-explicitly enable the hostinfo feature,
+explicitly enable the hostinfo feature (see below),
 
 =item *
 
-select which virtual machines can see any data,
+select which virtual machines can see any data (see L<hostinfo-set(8)>),
 
 =item *
 
-select which data they wish to disclose to virtual machines, and
+select which data they wish to disclose to virtual machines
+(C<guests.conf> below), and
 
 =item *
 
-select the frequency that virtual machines can ask for data.
+select the frequency that virtual machines can ask for data
+(C<guests.conf>).
 
 =back
 
@@ -205,7 +207,7 @@ controlling the security of the hostinfo system.
 Edits to this file take effect as soon as the next request is received
 from any guest.  You do not need to restart the daemon.
 
-B<However if this file contains any mistakes, then the daemon will
+However B<if this file contains any mistakes, then the daemon will
 exit> (ie. the default becomes no access).  The reason for the error
 will be sent to a system log file.  So after editing this file, you
 should check that hostinfo is available end-to-end (ie. from a guest),
@@ -218,18 +220,27 @@ C<[*]>.  A typical example would be:
 
  # Rule for specific qemu/KVM guest called 'guest1'.
  [qemu-guest1]
- interval 60
- physcpus off
+ interval       60
+ physcpus       off
  
  # Rule that covers all other qemu/KVM guests.
  [qemu-*]
- interval 60
+ interval       60
  
  # Catch-all default rule for guests.
  # This rule MUST be last in the file.
  [*]
- interval 1
- physcpus on
+ interval       1
+ availcpus      on
+ corespersocket on
+ memory         on
+ mhz            on
+ model          on
+ nodes          on
+ physcpus       on
+ ping           on
+ socketspernode on
+ threadspercore on
  #etc.
 
 In the section header, C<[hypervisor-guestname]>, the C<guestname>
@@ -264,21 +275,19 @@ available to it, every N seconds, which means in total there could up
 to M requests every N seconds per guest.
 
 If a guest exceeds the rate at which it is allowed to make requests,
-then the daemon sleeps before replying (just for that guest).
+then the daemon will after some number of violations stop talking to
+the guest.  The only way to restore service to the guest will be to
+reboot the guest or restart the daemon.
 
 Setting this to C<any> means there is no limit.  Guests can flood the
 host with requests.
 
-=item B<physcpus BOOL>
-
-Enable or disable requesting the number of physical CPUs available in
-the host.
-
-
-
-
+=item B<I<command> BOOL>
 
+Enable or disable the command named I<command>.
 
+The default for every command is disabled.  You have to enable
+each one that you want to allow.
 
 =back
 
@@ -378,31 +387,49 @@ Is the guest using the correct serial port?
 
 Use the L<hostinfo-test(8)> program in the guest to test this.
 
+=item 8.
+
+(Linux/Unix guests) Is getty attached to the serial port?
+
+On some operating systems, system daemons will attach themselves to
+serial ports.  Under Linux you can use the lsof command to check:
+
+ /usr/sbin/lsof | grep ttyS
+
+=item 9.
+
+(Linux/Unix guests) Is serial device not in raw mode?
+
+Client software should set the serial device to raw mode and
+disable echoing.  The usual way to do this is:
+
+ stty raw -echo < /dev/ttyS1
+
 =back
 
+Note that serial port settings like speed, parity etc. make no
+difference for these emulated serial ports, so that won't be a factor.
+
 =head1 FILES
 
 =over 4
 
 =item /etc/hostinfo/hostinfo.conf
 
-
 =item /etc/hostinfo/guests.conf
 
-
 =item /var/lib/hostinfo/
 
-
-
 =back
 
 =head1 SEE ALSO
 
 L<hostinfo-set(8)>,
 L<hostinfo-status(8)>,
-L<hostinfo-test(8)>,
+L<hostinfo-test(1)>,
 L<virt-install(1)>,
 L<virt-manager(1)>,
+L<hostinfo-protocol(5)>,
 L<http://fedoraproject.org/wiki/Features/Hostinfo>,
 L<http://libvirt.org/>.