--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+virt-what-cvm - detect if we are running in a confidential virtual machine
+
+=head1 SUMMARY
+
+virt-what-cvm [options]
+
+=head1 DESCRIPTION
+
+C<virt-what-cvm> is a tool which can be used to detect if the program
+is running in a confidential virtual machine.
+
+The program prints out a list of "facts" about the confidential virtual
+machine, derived from heuristics. One fact is printed per line.
+
+If nothing is printed and the script exits with code 0 (no error),
+then it can mean I<either> that the program is running on bare-metal
+I<or> the program is running inside a non-confidential virtual machine,
+I<or> inside a type of confidential virtual machine which we don't know
+about or cannot detect.
+
+=head1 FACTS
+
+=over 4
+
+=item B<amd-sev>
+
+This is a confidential guest running with AMD SEV technology
+
+Status: tested on Fedora 37 QEMU+KVM
+
+=item B<amd-sev-es>
+
+This is a confidential guest running with AMD SEV-ES technology
+
+Status: tested on Fedora 37 QEMU+KVM
+
+=item B<amd-sev-snp>
+
+This is a confidential guest running with AMD SEV-SNP technology
+
+Status: tested on Microsoft Azure SEV-SNP CVM
+
+Status: tested on Fedora 38 QEMU+KVM SEV-SNP (devel snapshot)
+
+=item B<intel-tdx>
+
+This is a confidential guest running with Intel TDX technology
+
+Status: tested on Microsoft Azure TDX CVM (preview)
+
+=item B<azure-hcl>
+
+This is a confidential guest running unenlightened under the
+Azure HCL (Host Compatibility Layer). This will be paired with
+B<amd-sev-snp>.
+
+Status: tested on Microsoft Azure SEV-SNP CVM
+
+=back
+
+=head1 EXIT STATUS
+
+Programs that use or wrap C<virt-what-cvm> should check that the exit
+status is 0 before they attempt to parse the output of the command.
+
+A non-zero exit status indicates some error, for example, an
+unrecognized command line argument. If the exit status is non-zero
+then the output "facts" (if any were printed) cannot be guaranteed and
+should be ignored.
+
+The exit status does I<not> have anything to do with whether the
+program is running on baremetal or under confidential virtualization,
+nor with whether C<virt-what-cvm> managed detection "correctly" (which
+is basically unknowable given the large variety of virtualization
+systems out there)
+
+=head1 RUNNING VIRT-WHAT-CVM FROM OTHER PROGRAMS
+
+C<virt-what-cvm> is designed so that you can easily run it from
+other programs or wrap it up in a library.
+
+Your program should check the exit status (see the section above).
+
+=head1 IMPORTANT NOTE
+
+This program detects whether it is likely to be running within a known
+confidential VM, but does I<NOT> prove that the environment is trustworthy.
+To attain trust in the environment requires an attestation report for the
+virtual machine, which is then verified by an already trusted 3rd party.
+
+The hardware features that this program relies on to establish facts
+about the confidential virtualization environment, are those features
+whose behaviour will be proved by verification of an attestation report.
+
+This program I<MAY> have false positives. ie it may report that it is a
+confidential VM when it is in fact a non-confidential VM faking it.
+
+This program I<SHOULD NOT> have false negatives. ie it should not fail to
+report existance of a confidential VM. Caveat that this only applies to
+environments which have been explicitly tested.
+
+If this program does print a fact, this can be used for enabling or
+disabling use of certain features, according to whether they are
+appropriate for a confidential environment. None the less, the VM
+I<MUST NOT> be trusted until an attestation report is verified.
+
+As a protection against false negatives from this tool, environments
+requiring high assurance should take one or more of these measures:
+
+ * The facts reported by this program I<SHOULD> should be measured
+ into one of the TPM PCRs
+ * The attestation report I<SHOULD> cover the facts reported by
+ this program
+ * The attestation report I<SHOULD> should cover the enablement
+ status of any features affected by decisions involving facts
+ reported by this tool
+
+=head1 SEE ALSO
+
+L<http://people.redhat.com/~rjones/virt-what/>,
+L<https://github.com/Azure/confidential-computing-cvm-guest-attestation>,
+L<https://virtee.io/>
+
+=head1 AUTHORS
+
+Daniel P. Berrangé <berrange @ redhat . com>
+
+=head1 COPYRIGHT
+
+(C) Copyright 2023 Red Hat Inc.,
+L<http://people.redhat.com/~rjones/virt-what/>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+=head1 REPORTING BUGS
+
+Bugs can be viewed on the Red Hat Bugzilla page:
+L<https://bugzilla.redhat.com/>.
+
+If you find a bug in virt-what-cvm, please follow these steps to report it:
+
+=over 4
+
+=item 1. Check for existing bug reports
+
+Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
+Someone may already have reported the same bug, and they may even
+have fixed it.
+
+=item 2. Capture debug and error messages
+
+Run
+
+ virt-what-cvm -d > virt-what-cvm.log 2>&1
+
+and keep I<virt-what-cvm.log>. It may contain error messages which you
+should submit with your bug report.
+
+=item 3. Get version of virt-what-cvm.
+
+Run
+
+ virt-what-cvm --version
+
+=item 4. Submit a bug report.
+
+Go to L<https://bugzilla.redhat.com/> and enter a new bug.
+Please describe the problem in as much detail as possible.
+
+Remember to include the version numbers (step 3) and the debug
+messages file (step 2) and as much other detail as possible.
+
+=item 5. Assign the bug to rjones @ redhat.com
+
+Assign or reassign the bug to B<rjones @ redhat.com> (without the
+spaces). You can also send me an email with the bug number if you
+want a faster response.
+
+=back
git.annexia.org / virt-what.git / blobdiff